Scientific Software

Ten best practices for scientific software development.

Learn More About This Project    

Barely Sufficient Software Documentation

 

Documentation is the cornerstone of any software project. But documentation should require minimal effort. Ideal documentation writes itself!

Why "Barely Sufficient" Documentation?

Anyone who's ever worked on any software project, of any kind, knows that documentation is always left to the last step, relegated to the category of "nice to have, but non-essential."

Barely sufficient software documentation recognizes the inherent difficulty of code documentation, and focuses on ways to create documentation that answers basic questions, and gives an idea of where to go in the code to get more details.

How Does Code Document Itself?

Ideally, even code free from any comments can be documented - assuming the developer has at least used sensible function definitions, input arguments, etc. (That may be an unrealistic assumption.) The trick to making this work is to document the functional API in a format that allows for users to search and interactively explore the code's API.

Doxygen

An excellent example of a software package that documents C and C++ code in this manner is Doxygen. This allows automated generation of documentation from source code. The key to Doxygen is that, with zero developer input, it still produces something of value.

But with additional developer input, it provides a much more sensible view of code, making for valuable documentation that's useful to both users and developers. This can be done through special comments and markup, for example replacing /* one C++ comment style */ with /** another C++ comment style */ and using special markup to document parameters, descriptions, and other features easily.

Another example:

void get_some_help() {
    /// This is a Doxygen comment that will end up
    /// in the documentation of the function get_some_help()

    ...

    // This is not a Doxygen comment
}

This makes generating detailed, nuanced, useful documentation very straightforward - as opposed to sitting down to a blank piece of paper and having to describe the entire structure of the code from scratch, plus document every function call, digitize it, tag it, etc.

The Visualization Toolkit is documented using Doxygen, so herei s a link to an exmaple of what Doxygen can output (with enough input from the developers): Visualization Toolkit documentation.

Epydoc

Epydoc is a package taking the same approach to Python code as Doxygen takes to C and C++ code. The charlesreid1.com wiki contains a page comparing different libraries for creating documentation of Python code here