Section 8.8. Internal Project Documentation

8.8. Internal Project Documentation

Properly understanding a large amount of source code can take a long time, as described in Section 10.3.1. One thing that can help is having documentation that describes how the different functions and methods in the code are supposed to be used.

The idea of documenting a function right where it's defined by adding comments to the source code is an old one. Just like raw text files, these comments need some structure to be more useful. Code documenters such as Javadoc and doxygen define special "tags" such as @return, which a method's comment uses to describe what is returned from the method. Others such as DocJet parse the comments as free text. Code documenter tools for languages that have classes are sometimes known as "class browsers."

Javadoc© (http://java.sun.com/j2se/javadoc) is a tool that comes with the no-cost JDKs available from Sun. It's easy to use to document a large amount of Java source code, though if there aren't any comments, it becomes more of a class browser. It generates HTML reports by default, but is extensible and can be used as a basis for any tool that analyzes Java source code. As of JDK 1.4, you can define your own tags for the comments.

doxygen (http://www.doxygen.org) is an open source tool by Dimitri van Heesch that can analyze C, C++, IDL, and Java source code; it can then produce a L^ATEX reference manual, HTML files, or XML documents that describe the different elements of the program. doxygen has plenty of documentation, which is a good thing because it has a lot of configuration knobs to play with. You can create dependency diagrams, though this feature can take hours for projects with over 250,000 lines of C source code. As well as a .tar file of its source code, doxygen has binary releases for GNU/Linux, Windows, and Mac OS X.

One commercial code documenter is DocJet (http://www.tall-tree.com), which can analyze C, C++, Visual Basic, some versions of IDL, and Java. Prices are on a complex sliding scale starting at $300 per user. The reason that DocJet stands out is that it parses both the programming language that is being used and the natural language in the comments, so you don't have to add tags. It runs only on Windows.

A few questions that are useful when evaluating this kind of tool are:

• Can all the elements of a language be documented, not just functions and methods?

• Is the location of comments flexible? Or must comments come before and never after a variable or enum, for example.

• Can you exclude parts of the product not just by class or filename, but also by method or function name? Is this customizablecould you exclude all methods that started with my_get or my_set?

• Can you customize the reports generated by the toolfor localization or other customization, for example?

• Is the language that the tool accepts for comments checked for errors? For example, Javadoc allows HTML in its comments, but you have to use a different tool to check the generated report for incorrect HTML.

One benefit of using an IDE such as Visual Studio or NetBeans© is that generated documentation can be added to the existing documentation. This also allows you to have real-time prompting for functions' names and parameters from within the IDE, so you don't have to change to a browser window to see the HTML report from a code documenting tool.