The Google Style Guide 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 documentation markup where appropriate.
You can build the doxygen documentation of Widelands usin 'make doc' from within the CMake build directory.
Building Sphinx documentation
First, you need to install Sphinx. On Ubuntu, call:
sudo pip install -U Sphinx sudo apt-get install python-sphinx
Then change to the sphinx directory:
Then run the commands that are documented in the
README. This will create an offline copy of the documentation.