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.
Wei-ju's OpenSource Blog 