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:

Class layout in Kolf 2 (cut-out)

Class layout in Kolf 2 (cut-out)

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

Advertisements

One Response to “Code documentation is really important”

  1. Monika Says:

    You are my hero now. Keep up the the good work.


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s