CompSci 307
Fall 2022
Software Design and Implementation

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 from Code Complete

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 should follow Javadoc conventions for all 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 program's design. Subclasses that are short and follow a standard pattern can be lightly commented.

Each source code file should include:

Submission Guidelines

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.

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:

Submission Guidelines

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:

Submission Guidelines

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. 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 in this course 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):

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

Be careful anytime you do 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 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