Code documentation is really important
July 27, 2009
One of the things I learned about during my continuing involvement in Kolf is the importance of code documentation. All of you will know user documentation (handbooks, tooltips, …), and developers know about API documentation. But developer documentation is also happening on a more abstract level. It doesn’t help if you understand what single functions do, if you do not get the big picture. How do these classes work together? And which class should I use in the code I’m working on?
These questions were exactly the ones I couldn’t answer when I was looking at the source code of Kolf 1. It might have been that I could get into it with enough time and will (it seems doable), but you see: Missing developer documentation raises the entry barrier.
I was enthusiastic to get proper, extensive documentation in Kolf 2. From the start, every class API has been documented (the obligatory lower level of developer documentation). Unfortunately, the high level documentation was going very slowly until last weekend. When I started to refactor some internals, I set the private goal to not proceed with the refactoring until I documented the last part. Currently, I’m working on documentation for the basements of Kolf, which look like this:
I would like to encourage every developer out there to write high-level developer documentation, to be sure that work on his code can continue even if he is not available anymore. Writing documentation is also a good opportunity for reflections on the class layout and the semantics of the classes.
P.S. You might’ve noticed that above graphics uses TeX fonts. It’s actually written in LaTeX (with PGF/TikZ), the sources are in SVN at trunk/playground/games/kolf-ng/doc (view in WebSVN), where the complete documentation is located (see the README for how to compile).