Software Documentation

Most programmers enjoy writing documentation if the documentation standards aren't unreasonable. Like layout, good documentation is a sign of the professional pride a programmer puts into a program. --- Steve McConnell. Code Complete. Microsoft Press, 1993

While the code ultimately determines how the program runs, it does not serve well to describe how the program is organized, what decisions were made while the program was constructed, or even the priorities of the project. Nor is code for large projects concise, so it does not allow new developers to quickly get an overview of the entire program. Thus, programs are often supplemented by documentation that serves to explain such fuzzy concepts. Successful programmers must be able to write about code at a variety of levels of detail in order to get their knowledge and ideas across.

Your goals in writing documentation are to help others use, understand, and eventually maintain/extend your code in as concisely and unambiguaously as you can. Each of these goals should expose more details of the design and its rationale, going from discussing packages and classes conceptually eventually to discussing actual coding matters. As you consider different design alternatives, you should record why you did not choose each one.

Finally, documentation is read much more often than written, so write to your audience --- each other (not me!).

Comments Within the Code

Comments within your code should follow Javadoc conventions so they can be exported automatically to web pages. Note, HTML and examples can be written directly into Javadoc comments. Superclasses, interfaces, and packages should be heavily commented to describe their role in the design of the program. Subclasses that are short and follow a standard pattern can be lightly commented.

Each file should include:

• names of all people who worked on the file
• comment each class to describe its
  • purpose (why would anyone use it)
  • invariants (what situations or values might cause it to fail)
  • dependencies (what other classes or packages it depends on)
  • an example of how to use it
  • any other details users should know
• comment each method (and especially abstract methods)
  • purpose (why would anyone use it)
  • invariants (what situations or values might cause it to fail)
  • parameters (purpose beyond their name if necessary)
  • return value
• inline comments should be kept to a minimum (because the code should be made to be readable on its own)
  • comments should never simply restate the code, but always state its purpose
  • code hacks, or other non-standard code, should be factored into a separate method and commented extensively
    

Other Documentation

Your out-of-code documentation should be organized in such way to allow another programmer to understand your program's design and organization so that they might evaluate it, debug it, or extend it. Your document should describe how your program is organized and why it was done that way. While you may assume your reader has a technical background, you may not assume that she has experience with this specific project or your design discussions.

Two files should serve to document your code and be included in the top level folder of your project:

• README
  • names of all people who worked on the project
  • date you started, date you finished, and an estimate of the number of hours worked on the project
  • each person's role in developing the project
  • any books, papers, or online resources that you used in developing the project
  • files used to start the project (the class containing main) and test the project (the class containing TestSuite)
  • any data or resource files required by the project (including format of non-standard files)
  • any known bugs, crashes, or problems with the project's functionality
  • highlights any extra features included in the project
• design document
  • provides the high-level design goals of your project
  • explains, in detail, how to add new features to your project
  • justifies major design choices, including trade-offs (i.e., pros and cons), made in your project
  • states any assumptions or decisions made to simplify or resolve ambiguities in your the project's functionality