Style Guide

2022-08-15. Filed in data-structures,fall-2022.

The most important role of a set of coding standards is consistency. No group of programmers will ever completely agree on the best way to format code. Should code blocks be indented with tabs? With spaces? How many spaces? Two? Four? Eight? Where should opening braces be placed? The fact is, none of these things really matter that much. What does matter is consistency. It is very painful for a group of people to work together on a shared code base if they don't agree on some set of common standards.

Code submitted for this course must conform to the Google Java Style Guide. We are using these standards because they are well-documented, widely-used, and enforced by our development environments.

The Google style guide is mostly concerned with low-level formatting issues like indentation and line length. Keep in mind that it is possible to write very bad code that is properly formatted and will pass automated checks. Don't do this.

Checkstyle

The autograders on Gradescope will use Checkstyle to automatically check the formatting of your code. You will save yourself time if you run Checkstyle locally before submitting. Your repository is already set up to use the CS 240 style rules using this Checkstyle configuration.

In case you need to set up Checkstyle yourself in IDEA, follow these steps:

Inspect the style violations and issue new checks in the Checkstyle panel in the bottom toolbar.

Other Requirements

Your code must meet these additional requirements, which won't be inspected by the autograder but will be inspected by your instructor.

Names

Selecting informative names is one of the most important steps in writing readable, maintainable, and correct code. Variable names should clearly describe what the variable is intended to contain.

All names should be descriptive and readable: subtotal is better than s and grade is better than grd. Variable names should balance clarity with brevity. The name person is better than currentPersonObject. However, per is worse than either. Does it stand for percentage, person, or permitted?

Non-Javadoc Comments

The point of comments is to clarify code that might otherwise be difficult for the reader to follow. Well-organized Java code with informative variable names should require few comments inside of method bodies.

In-line comments must come before the code that they are describing or, if brief, on the same line following the code. You must use normal English spelling and grammar. Phrases are okay, but cryptic abbreviations and unintentional misspellings are not.

Honor Code and Acknowledgments

Every programming assignment must contain the following section which follows the class description or must cite any sources used, including any teaching assistants. You should either include this statement in all files or minimally it may appear in the file containing your main method. The statement might look something like this:

/*
 * This work complies with the JMU Honor Code.
 * References and Acknowledgments: TA Glenda helped me
 * with the foo method.
 */
/*
 * This work complies with the JMU Honor Code.
 * References and Acknowledgments: TA Glenda helped me
 * with the foo method.
 */

If you received no help, the statement might look something like this:

/*
 * This work complies with the JMU Honor Code.
 * References and Acknowledgments: I received no outside
 * help with this programming assignment.
 */
/*
 * This work complies with the JMU Honor Code.
 * References and Acknowledgments: I received no outside
 * help with this programming assignment.
 */

This acknowledgment is not necessary for lab assignments. Note the single star after the slash; this is not a Javadoc comment.

Miscellaneous