About source code documentation

Code documentation

Everybody likes well-documented source code. Nobody likes documenting source code.

Everybody positively hates outdated docs. But nobody updates the docs.

Fortunately, Doxygen allows you to write your doc where you remember to keep it up to date: right in the code. Nevertheless, it produces optically pleasing and very, very informative HTML (and other formats) documentation, including graphical inheritance diagrams and call graphs.

For you this means: do write doc (look at existing code for quick learning), run 'scons doc' and peruse. You'll like it.

And if you think it's obvious what your code does: it's not. Right now it is, in half a year it isn't and to a newcomer it might never be. So please, please document your code. It's not that hard, really.

A few guidelines (guidelines, that is; not laws :)) )

• Document every function/method and every variable
• Do so even if it's use is obvious (loop indices don't count, 99% of temporary variables don't count either 8-))
• Do so even if it's repetitive. In the finished documentation, function and variable ordering may be different than in your code
• Omit the constructor only if it really does nothing but setting simple default values
• Omit the destructor only if it's empty
• Document variables in their header file, functions/methods in their .c-file.
• ALWAYS document parameters and return values. Allowed/disallowed values and meanings are very important (boolean return value? ok, but what does 'true' mean x-) ). Remember that the people looking at the docs might have no idea at all what this is about and do not want to read your code, they just want to use your function
• At the beginning of a class definition, tell us what this class is about. How does it fit into the big picture?
• Do not describe in detail, we can read the code (you wrote it so we can, didn't you? ;-) ). Tell us the big picture. Why did you choose a certain algorithm? Is there anything that should not be done when modifying this code? Why does the string the_girlfriend default to "Emily" ?

Over time, more and more of the existing comments are being converted into doxygen format. If you advance this process, everybody will love you :-)