Latest Posts

Changes in AboutSourceCodeDocumentation

Editor Comment

Shortened and updated.


Revision Differences of Revision 4

## 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 'make doc' ¶
from within the CMake build directory 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. ¶

See also information about LuaScripting. ¶

### 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 :-) ¶
The [Google Style Guide](http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml) contains a lot of valuable information about this topic. You should read it start to finish - Widelands is drifting towards using it and is already using big parts of it. Keep the following in mind: ¶

* Try to write self documenting code (i.e. useful, descriptive variable names), but document funky implementation details close to where they are defined. ¶
* Document each class and each method in the class in the .h file (not in the .cc file) so that a caller of this method can figure out how to use it by just looking at the header. This means adding a short introduction of the use of the class before the class and a short documentation for callers before each method definition. ¶
* Use [Doxygen](http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html) documentation markup where appropriate. ¶

You can build the doxygen documentation of Widelands usin 'make doc' ¶
from within the CMake build directory. ¶

Lua methods documentation are extracted directly from the Source code and is formatted using [Sphinx](http://sphinx-doc.org/), there you have to document in the .cc file. ¶
See also information about LuaScripting.