Unit testing and tracer code

April 4, 2007

There are moments during development where you realize some things are not that easy, here is a result I achieved experimenting with rectilinear connection editing earlier today 🙂

Rectilinear bug

Here is what I really wanted to do:

Expected result

It is clear that it is a good idea to create a test suite for something as complex as rectilinear editing. When it comes to an interactive application, you often reach the limits of test-driven development. In particular, how do you express the tests about how an interaction should work, if you can’t imagine it ?

Therefore, if I want to design an interaction, I usually do “explore-first”, which means to write tracer code, like in the above example. It helps me to explore how to write the code and/or the tests when I have absolutely no idea. It is not a prototype in the strictest sense, since the code has production quality (or what I consider to be production quality) from the beginning. I just can’t write prototypical code, which for me is a good thing, because once I have fleshed out the functionality, I am practically finished.

Sometimes you have to scratch and bite to impement a feature. This is particularly true for client applications, where you can lose yourself in the details (now I am happy not to have used AJAX, I probably would have lost myself in Javascript 🙂 ). I am now the second day into this feature and this one turns out to be even more complex than I thought. Granted, I could just have ducked away, because rectilinear connections can be created using the generic connection type. That’s exactly what I don’t want. Rectilinear connection editing is a useful feature, because it let’s the user create this particular connection style with fewer interactions than the generic way would do.

This is also an example that even though the general advice is to tackle the hardest problems first, that this is not always possible. In this case, I needed to have the basic abstractions available and get the understanding about them in order to design the feature in this context. Often the understanding of the system in development has to grow before more difficult tasks can be executed.

Even though I could probably hack it in until tomorrow, I would not be happy without the tests in place. I take a rather liberal approach to unit testing, but in this case, I insist to have a test suite. So I will need to push my release date to next Monday. I am sure that these additional four days will result in higher quality.


Editable connections

April 2, 2007

I decided to stretch the release periods from formerly 7 days to 10 to 14 days. I’ll use the longer time frame either to tackle harder problems (such as connection editing and nesting) or to include more features.

This release cycle, there are only two features, which I consider important, but a little more difficult: Multiple selections and editable connections.

As expected, multiple selections was indeed very simply implemented using the Composite pattern, with that out of the way, the editor feels much more natural and some code cleanups could be applied on the way.

I am now seeing that editing connections is a comparatively difficult feature, so I assigned five days to get that right for both simple and rectilinear connections. I’ll use more if I need to, because I want it to be both sufficiently clean and usable. To illustrate the idea, I have created a package diagram with a few dependencies where I have edited the connections, with editing, I mean to create new control points, so that connections can be drawn a bit more flexibly.

Editable connections

As shown, it works already for connections which are not rectangular. This is the easier case, rectangular connections have a few rules to take care of.

I originally planned to include package nesting in this release, which is another nice feature with a good learning effect. It does not fit for the current release time frame but I consider it very important, so I moved that to the 0.12 release.

TinyUML conception phase – a post mortem

March 28, 2007

At the start of the project, I decided to write this post mortem should I reach the Quina milestone. I find it useful to review the past efforts and to analyze bad and good decisions as well as difficulties that might have shown up during the process in order to learn from them. Learning is the main motivation behind this project, aside from the hope that it will develop into the tool that meets my needs.

What went right

The name

I originally chose a different name for the software, but it came to me just the day when I registered it. I wanted to communicate my intention to create something simple and lightweight, and it serves well as a reminder of that intention. Hopefully it will not develop to be as “simple” as SOAP 🙂

Lessons learned: Choose a good name for your project, it is the first thing to communicate the goals

Project setup

I have spent a significant time to setup the development in the beginning, the decision to use Maven 2 gives me permanent control over the project and supports the release process. Unit testing was also included in the process from the start, I include it in any project except the simplest Python or Ruby scripts. It increases my confidence and understanding about the system the more tests I add.

Lessons learned: Start with a well set up project environment to automate boring, repetitive tasks. Write unit tests, they are your safety net

Decision not to use a graphical framework

At the beginning I had to make the choice whether to use a generic graphics editing framework or to write the graphics editing code by myself. I opted for the latter because graphics editing is the central part of TinyUML and in order to get a good understanding, I wanted to work on the abstraction level of Java2D. In general, if integrate third party code, I like to reuse the best code available. This is reflected in using Batik. I will probably integrate more third party libraries as the software evolves so I can entirely focus on the application itself, but it not without good evaluation.

Lessons learned: Reuse high quality code, “reinvent” from scratch if you believe it is beneficial to your project

Constant refactoring

Yeah, I knew that was the right to do, because like unit testing, I do it every day, so I know it works. If you want to ensure that you won’t run into a dead end some day, you’ll need to adapt your system so that changes can be made easily and make it reflect your understanding as best as you can. All this “never touch a running system” stuff is nothing but a huge pile of bull poo-poo and the best way to left your system turn into such.

Lessons learn: Refactor regularly

Documentation and project management tools

I started to include several new documentation tools into the process that I wanted to try out: Wiki, Blog and Backpack. These are great tools to just dump my thoughts into it. It is just too easy to forget things. Backpack is a great tool to manage “the list”. I often shift things around and reprioritize items, Backpack’s Todo-list feature does it all very efficiently.

Lessons learned: Write everything down ! Do this in a safe place, not just on a piece of paper. Manage a Todo-list !

Project pace

The decision to commit myself to weekly releases paid off, because it really helped me to stay focused. A week is a very predictable unit of time and you can only do a small amount of work, so I am forced prioritize and stick to the important features.

Lessons learned: Stay focused !

What went wrong

File releases too early

I released the first file release (“Gogo”) just for myself to tighten the release process. I did not expect that people would really download “Gogo”. They did and I was a little embarassed, because I had only worked a week on it and all it did was moving around package elements. Then other web sites started to release “Moogle” as a 1.0 version, so I felt pressured to provide a version number on the next release.

Lesson learned: Release to the public when you feel that you want to show it. Give every release a version number, code names are just for the developers.

Persistence model decision was too late

I actually intended to go with a custom file format based on XML and just proceeded under this assumption. When I actually came to the point where I wanted to implement save and read, I decided to go with serialization instead. In fact, I should have made all the classes which I wanted to persist serializable from the start, even if I would have gone with the custom format. It forced me to conciously think about which data needed to be persisted.

Lesson learned: Consider to design the classes which are part of the persistence mode to be serializable.

Not choosing GPL from the beginning

Originally, I planned to go with the Apache License and the earliest releases are licensed under that license. I never felt comfortable with it, and that feeling became stronger the more progress I made. Had I written a library, that would have been the right decision, but the GPL just “feels” better for an application. I relicensed the code under the GPL because I care for my code. I have nothing against other licenses and might choose one or another according to the situation.

Lesson learned: Consciously think about what license your code should be released under, it’s your code, you should care

Where to go from here

So far, the project progressed exactly as I planned it. There were no big surprises, except perhaps that it went so well. I had expected to face some technical obstacles, but nothing of that quite yet. At the end of each of the releases there were often some open design issues that were resolved by regular refactoring and a better understanding. Many of the hardest principle questions are solved or will hopefully be solved in one of the next releases.

Despite its name, TinyUML is a rather large software tool. That’s the nature of this kind of software. The important task for me will be to identify the important features and regularly add functionality that really makes sense. The software has some way to go, but for now, I reached the goal to create something that I can start to use. I will build on this foundation.

Quina milestone

March 26, 2007

Quina screenshot

Just exactly on schedule, I TinyUML has now reached the “Quina” milestone. The goals were to finalize a persistence model and to add more connection types. This is the last “conceptual” milestone, since “Quina” was intended to be the first “dogfood” release for myself. It is also the release where I planned to review the progress so far.

As opposed to my earlier plan, I wiggled myself out of the temptation to create a custom file format and use serialization instead. The downside is that the files are not compatible between releases for now. The advantage is that I can focus on the application instead of half-baking something. Opting for serialization already paid off, because I had to conciously review the design. There is also the possibility to integrate XStream to make the file format more robust to changes.

Creation of elements is now refactored to employ the Prototype pattern. It works very well now. Overall, I feel that with the better understanding, the design becomes tighter on every release cycle.

According to my roadmap, I’ll be due for the next release in exactly one week. I have to push that a few days to the back, because I need a short break. I’ll use the time to do a post-mortem on the concept phase.

Looking back, it is now six weeks since I started the project. Could I have progressed faster ? Definitely. Everyone can. I could probably have done it three times faster, but would have ended up with the need to rewrite the whole system at some point (and probably giving up in doing so). It is nice to see how a system changes over time and directly reflects the understanding.

Stallman and Free Software

March 23, 2007

These days I remember joining a presentation that Richard Stallman gave at my university (Freie Universität Berlin, which means “Free University of Berlin”), about ten years ago. At the beginning of the talk he promised to “show us some slides” – and then took his shoes off to slide on his socks in front of the audience.

He then continued to explain to us his ideas about why software should be free. I was in my first or second year and at that time, I was more struggling to understand the computer science material, so I was too green to understand him.

I come from the university where the JacORB project was born, I have worked with the original author of DOC++ and knew the enthusiast, who has maintained vim.org for many years, so I have a natural affinity to Free Software. Free Software is a way for the small team that I currently work in to realize our projects economically.

When Stallman gave his presentation, I thought “yeah, that’s the guy who wrote emacs and the gcc”, which proves that besides being a political activist, Stallman is also an incredible hacker.

Probably it needs the experience and skill of such a person to come to the conclusion that software should be free and to fight for it in the ways he does. This reminds me of martial arts, where practicians who have mastered the art are not tied to form any longer.

Recently I often think about his presentation, because I feel that ten years later, with becoming a better programmer, I start to understand him better. Still I know I have not “arrived” yet.

Chocobo milestone release

March 19, 2007

Chocobo screenshot

I just released the Chocobo milestone and can happily say that I am well on track at the moment. One of the lessons I am learning on this project is how to deal with a very limited amount of time (my free time) and at the same time keep having a private life.

One way is to think hard about which features really need to be in the software, the other is to release on a regular schedule. I am keeping a Todo-list in GTD fashion which I update almost every day and features keep getting shifted around.

This week, there was quite a bit of refactoring and bug fixing before I  went to tackle the largest feature so far: editing class contents. Class elements can display attributes, methods and stereotypes, which are in separate compartments that can be hidden or shown. It turned out that the earlier decision, to implement compartments and labels as separate classes now pays off. A lot of the things worked right away.

There is still a huge amount of work waiting, but Quina is the next release, which I have declared my “first dogfood”.  In fact, the feature set of Chocobo is almost sufficient to do some work with it. Association types and inheritance will be in Quina, and a number of other features that I did not decide on yet.

TinyUML Version 1.0 ???

March 15, 2007

Somehow, TinyUML got a 1.0 version number on Softpedia ! Very funny, I am not even out of my internal releases yet… That’s what I get for putting my internal releases out publicly 🙂 Apparently, someone even drew a screenshot with it. Interestingly, when I click on “More programs by this producer”, ZMPP does not show up, even though it is indeed already registered in Softpedia (with a real version number).

In fact, I do not even use the tool myself at the moment, I still try to shoot my tracer bullets and choose features that are difficult enough to push the project forward. So, the 1.0 Version number is still some time away, TinyUML does not yet have any version number, this early in the development.

For that future version 1.0, I have decided to go with two diagram types:

  • structure diagrams (class, package, component)
  • sequence diagrams

These are the ones I am using most often, so I’ll focus on these and add the rest over time.

According to my roadmap, I will reach the “Quina” milestone in two weeks, after which I will review the project’s progress. Probably I will have to label the releases as public then (and give them version numbers), since they are public now anyways (even though I don’t consider them really useful currently).