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

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 unambiguously as you can. Each goal 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 on public methods and their packages should follow Javadoc conventions so they can be exported automatically to web pages. Note, HTML, examples, and detailed analysis can be written directly into Javadoc comments. Super-classes and interfaces 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)
  • assumptions (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)
  • assumptions (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 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 documentation 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.md (due when the project is submitted)
  • 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, online, or human resources that you used in developing the project
  • files used to start the project (the class(es) containing main)
  • files used to test the project and errors you expect your program to handle without crashing
  • any data or resource files required by the project (including format of non-standard files)
  • any information about using the program (i.e., command-line/applet arguments, key inputs, interesting example data files, or easter eggs)
  • any decisions, assumptions, or simplifications you made to handle vague, ambiguous, or conflicting requirements
  • any known bugs, crashes, or problems with the project's functionality
  • any extra features included in the project
  • your impressions of the assignment to help improve it in the future
• DESIGN.md (due when the analysis is submitted)
  • 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