Software Documentation

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 the course staff!).

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 and IntelliJ can help generate 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.

Basic code comments should be added during the project, when new classes or public methods are added to the master branch, but final, complete, Javadoc can be completed when the analysis is submitted.

Each file should include:

• names of all people who worked on the file (using @author tag)
• 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 public 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

This project file must be completed when the project's Complete functionality 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., required resource files, 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

This project file must be completed when the analysis is submitted and it is typically an update of your planning Design Document to describe the final, implemented, version of the code. Any part of it can be used within your individual analysis as appropriate

• what are the project's design goals, specifically what kinds of new features did you want to make easy to add
• describe the high-level design of your project, focusing on the purpose and interaction of the core classes
• what assumptions or decisions were made to simplify your project's design, especially those that affected adding required features
• describe, in detail, how to add new features to your project, especially ones you were not able to complete by the deadline