Developer

Speeding up code documentation

Documentation is a crucial part of a software project. It is used throughout the project and it should outlast it to allow adequate maintenance. See how the Javadoc tool can help you to create and maintain in-sync developer documentation.


It is not a secret that documentation is a crucial part of a software project. It is used throughout the project and should outlast it to allow adequate maintenance. Unfortunately, a documentation process can be time consuming and complex, becoming a burden for developers that leads to documentation which is both incomplete and unsynchronized with ongoing modifications. Source code documentation is a significant part of the whole documentation process, and it is where the javadoc tool can help. Together with a simple text editor and an accurate project directory structure, this tool can help you can speed up and improve code documentation.

Project directory structures
A normal software project has a set of documents such as requirements, specifications, tests, and an integration plan that a system developer has to work with. She also needs to maintain and access them easily. Let’s consider a typical directory structure that is suitable for a project:
/prj-1
       /classes
       /doc
       /resources
       /spec
       /src
       spec.html

The /classes directory stores the compiled Java class files, /doc has the documentation, /resources has project resources, /spec has the project documentation, and /src has the Java source files. The spec.html is a mapping file which I'll discuss later.

Or it can be like the snippet below, where project-related documentation is placed one level higher than the source code.
/prj-2
/code
/classes
/doc
/resources
/src
spec.html
       /spec

The benefit of this structure is that it is clearly packaged and thus addressable from the /src directory where source files are located. Either structure works fine. For the rest of the examples in this article, we'll be using the first directory structure.

Using the directory structure
Assume you have implemented an algorithm that is thoroughly described in a specification and now you want to document this code. Instead of retyping or copy-and-pasting the algorithm’s description from the specification, you would be better off providing a link to the original place in the specification. It makes documentation faster and, more importantly, it does not duplicate the original information and thus keeps code comments in sync with it.

A link from a source file to a project-related documentation located in the /spec directory can look like the following code. You should use HTML and Javadoc synopsis for creating links. A link can point to documents stored in different formats that can be viewed or opened with your browser.
/**
*  Process a customer order according to the
*  <a href="../spec/specification.html#cust-order-proc">specification</a> and
*  <a href="../spec/requirements.rtf">requirements</a>
*/
public void processCustomerOrder() {
...
}
/**
*  Creates and sends
*  <a href="../spec/specification.html#cust-order-diag-resp">
*  a response message</a> according to
*  <a href="../spec/specification.html#cust-order-diag">a customer request</a>
*/
public void generateCustomerResponse() {
  
}

This approach works fine if the project-related documentation is kept and distributed along with the source code. However in this case, the source code comments are highly coupled with the particular document names and locations, and any changes in those destroys the comment’s consistency.

To avoid this drawback, you only need to provide a mapping between links from the source code to particular documents. This is easy to carry out by using a mapping file; for example, a spec.html contains mapping between names used in links within source files and real names of referenced documents. You can see the example of a link from a source file to some document using the spec.html mapping in Listing A.

This additional level of name-location separation allows changing names and locations of the referred documents without modifying the source code from where the references are made.

Linking to sequence diagrams
Another example of a place where you might want to link external documentation to your source code is in high-level design documentation, including use-case or sequence diagrams. Sequence diagrams are very descriptive when you want to specify system communication, interaction, or interface with another system or its components. Unfortunately you can not automatically generate code from a sequence diagram, nor can you re-engineer source code back into a sequence diagram. Thus, you have to simultaneously maintain both the diagram and the source code. It becomes easier if you link a sequence diagram—for example a message passing between two actors—from a piece of code that realizes it. Assuming your sequence diagram is a simple ASCII diagram, you might create an anchor like this:
   Customer                                         Processor
   ————                                          ————-
      |                                                  |
      | OrderRequest                                     |
      |————————————————————————->|
      |                                                  |
      |                                                  |
      |                                                  |
      |                                                  |
      | <a name="cust-order-diag-resp">OrderResponse</a> |
      |<————————————————————————-|
      |                                                  |

And then, link to this through your spec.html mapping file.

The documentation process, arranged in such a way, is comparatively simple and flexible. It requires only a text editor, the Javadoc tool, and perhaps a version control system. You do not need fancy (and expensive) CASE tools.

Editor's Picks

Free Newsletters, In your Inbox