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 level of documentation 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, 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 Teaching Team!).

Internal Documentation

Your internal code documentation must follow Javadoc conventions for your public classes, methods, and packages so they can be exported automatically as 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.

Each code file should include:

• names of all people who worked on the file (using the @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 (i.e., other programmers) should know
• comment each public method (and especially abstract methods)
  • purpose (why would anyone use it)
  • assumptions (what situations or given values might cause it to fail)
  • parameters (purpose beyond their name if necessary)
  • exceptions (why any exceptions might be thrown)
  • return value (and any limits or expectations about the value returned)
• inline comments should be kept to a minimum (because the code should be readable on its own)
  • comments must never simply restate the code, but always state its purpose/intent
  • code hacks, or other non-standard code, must be factored into a separate method which is commented extensively
  • code that thoughtfully does not follow standard code or design conventions must be justified with comments
  • code borrowed from other sources (e.g., tutorials, StackOverflow, or class examples) must refer to their origin with comments

Submission Guidelines

• Each person is responsible for commenting the code they wrote and anyone's comments can be used within your individual Analysis as appropriate.
• Some basic code comments should be added during the project, such as when new classes or public methods are pushed to the master branch (specifically, no code should be pushed that is completely uncommented).
• Final, complete, Javadoc comments must be completed when the project's Complete functionality is submitted.

External Documentation

Your external documentation should allow another programmer to understand your project'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.

README.md

A README is a text file that introduces your project to another developer to help them get started using or working with your code.

This file should be included in the top level folder of your project repository and contain the following information:

• 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
• any books, papers, online, or human resources that you used in developing the project
• attributions for any resource files (images, sounds, etc.) in the program
  Note, all resources must be royalty free and not "stolen" off of the web, using these sites, a proper Google search, or pay attention to the Creative Commons licenses on web sites.
• files used to start the project (the class(es) containing the main() method)
• 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 (e.g., 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 noteworthy features (so we do not miss them in the grading)
• your impressions of the assignment to help improve it in the future

Submission Guidelines

• As a team, complete this file when the project's Complete functionality is submitted
• Any part of this file can be used within your individual Analysis as appropriate

DESIGN.md

This document is typically an update of a planning Design Document to describe the final, implemented, version of the code to provide a detailed roadmap for other developers to understand your project's design goals.

This file should be included in the doc folder of your project repository and contain the following information:

• names of all people who worked on the project
• each person's role in developing the project
• what are the project's design goals, specifically what kinds of new features did you intend 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
• address significant differences between the original plan and the final version of the project
• describe, in detail, how to add new features to your project, especially ones you were not able to complete by the deadline

Submission Guidelines

• As a team, complete this file when the individual Analysis is submitted
• Any part of this file can be used within your individual Analysis as appropriate

Code Formatting

How code is formatted can be highly personalized, but it should not be because more often than not it is a team decision that is imposed upon you when you join because, when working as a team, it is more important that code is consistently formatted in order to remove an unnecessary burden to reading each other's code (much like reading a book written by multiple authors can be annoying if they all use different styles). Amazingly, not following the team's Coding Conventions is the number one reason Merge Requests are initially rejected.

Thus, for team projects in this course, your team must use the same code formatting rules; however, rather than spending time trying to come to an agreement amongst yourselves, all projects will use Google's Java code format standards. This requirement can be met relatively painlessly within IntelliJ, using the following steps (and here is a video showing them):

• Download intellij-java-google-style.xml from its GitHub repository
• Go to the IntelliJ menu and select Preferences
• In the dialog that appears, select Editor → Code Style
• On the line that says Scheme, click on the gear icon after the Combo Box with the tooltip Show Scheme Actions
• Click on Import Scheme → IntelliJ IDEA code style XML
• Select the previously downloaded XML file and then Open
• Finally unselect the option Enable EditorConfig support before clicking OK to close the dialog box

You can now reformat the code in any file to follow these conventions anytime by selecting the menu Code → Reformat Code.

Be careful about when you choose to this in your teams, but especially the first time, because it will likely change every line of code in the file which may lead to unpleasant, and unnecessary, merge conflicts. Anything you add when coding after doing this should automatically follow these conventions but, to be sure, before pushing any code it is a good idea to use the Reformat Code menu option only in the files you changed (or you can add the Save Actions plugin to your version of IntelliJ to do it for you automatically).

You can also setup IntelliJ to monitor formatting issues (like it does with other issues with yellow warning marks on the right edge of the editor window) by installing the CheckStyle plugin and turning it on either

• Manually: Its issues will be included automatically when you select Analyze → Inspect
• Continuously: Go to Preferences → Tools → CheckStyle and select "Treat Checkstyle errors as warnings" and "Google Checks" and then OK to activate