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).

“Moogle” milestone release

March 13, 2007

Release “Moogle” screenshot

I managed to ready the “Moogle” milestone release one day later than I originally planned. This time there was a lot of work around the project: Establishing Mantis as my tracking system and changing the license to GPL. I never felt comfortable with doing the project on the Apache 2.0 license, because I am more familiar with the GPL and it goes better with my personal view about software freedom.

The sourceforge tracker would probably have been perfectly appropriate for my needs, but using Mantis gives me an opportunity to learn a new tool. I like to see how other people write software and learn from them, I have worked with Bugzilla, and while I can use it, I prefer simpler interfaces like Jira or in Mantis.

Actually there were only three new features I added this week: Compartments, rectilinear connections and multiline editing. These are central features, because I am still in the phase of creating the building blocks of the system.

The rectilinear feature took me the longest to add and in fact, I need to refine it in later versions. Basically connections between the main elements (associations, dependencies, inheritance etc.) could be implemented by only one style of connection, I have grown used to the rectilinear feature of many drawing programs and so choose to implement it. I have to admit, it seems not that easy to get it to “feel right”. Every time I work on an application that is primarily dominated by the user interface, I am amazed at the amount of detail that needs to go into it to make it to “feel natural” and it makes programming user interfaces a greater challenge than writing a server application in my opinion. Technology is one thing, but getting a feature to work according to one’s expectation involves more than just technical skill.

Looking at the fields of computer and video games, the great games all have great balance in their user interfaces and application developers can learn a lot about designing interfaces by looking at a computer game.

The next release is named “Chocobo”, another internal release, that will add some more features towards a usable tool.

Kupo! Prerelease

March 2, 2007

TinyUML progresses faster than I initially thought, my builds already look like real UML 2 diagrams:

Kupo! Screenshot

It is now possible to create package diagrams with dependencies and component diagrams. Notes exist only as a display concept, but that will change soon. They are one of the trickier things.

I removed a lot of code in this release because I don’t need it at the moment and it distracts me from the important stuff. My Kupo! release is not yet through since there are a few rough edges that I want to get fixed this week, but since it seems that people already download the releases, I wanted to offer them a bit more than the “build works” Gogo release. This one can export PNG and SVG as well.

I further noticed that I can not keep the two-week cycle, because progress is simply too fast and I am an impatient person, so I try to release as often as I add more useful working features.