Documentation¶

Overview¶

Documentation should be part of your project’s codebase and developed synchronously with new features and fixes. Three types of documentation should be included:

End User Documentation
Reference [API] Documentation
Code Comments

Parse published an excellent primer on documentation.

Shining examples:

End User Documentation¶

Documentation for the end user consists of guides and tutorials. Markdown, especially github flavored markdown may be a good choice for small projects. Restructured Text (reST) in the form of Sphinx is strongly recommended for non-trivial projects. It can easily be built automatically with readthedocs

reST syntax guide, reference, and cheat sheet.

Reference [API] Documentation¶

Most languages have some de facto standard(s) for API documentation. Pick one and use it.

For python these are docstring formats, currently either numpy (example) and google’s pyguide.

Automated tools such as Doxygen may be able to aid in creating some of this.

Reference documentation should be up to date before every merge from a feature branch. Incorrect documentation is worse than no documentation (goes for comments too).

Code Comments¶

Code comments should describe complicated or non-obvious code for future maintainers. Do not describe what the code does, but rather what you are trying to do with the code. E.g. from pyguide:

# GOOD COMMENTS describe problem and explain non-obvious code:
# We use a weighted dictionary search to find out where i is in
# the array.  We extrapolate position based on the largest num
# in the array and the array size and then do binary search to
# get the exact number.
...complicated search algo...

if i & (i-1) == 0:        # true iff i is a power of 2

# BAD COMMENTS describe code:

# Now go through the b array and make sure whenever i occurs
# the next element is i+1
...some obvious loop code...

# OR WORSE:
a++; #add one to a