Changes in AboutSourceCodeDocumentation
Editor Comment
Corrected a few syntax errors and removed unused bulletpoints
Revision Differences of Revision 1
## 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](http://www.doxygen.org/) 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, 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 :-) ¶
¶
¶