Style Guide for CS 240

Google Java Style Guide

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 inconvenient 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 supported by development tools.

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. See Section 3 below for some additional style requirements.

Useful Style Tools

Checkstyle

Web-CAT will use Checkstyle to automatically check the formatting of your submitted code. It may be convenient for you to run Checkstyle locally before submitting. This configuration file encodes the formatting requirements:

• google_checks_5_8.xml

Note that Web-CAT is using an old version of Checkstyle that may be slightly pickier than newer versions. This means that your code might pass Checkstyle tests locally, then fail some tests when you submit. If you want to avoid this, you should download Checkstyle version 5.8. You can find it by following the link at the bottom of the Checkstyle installation page.

Eclipse Auto-Formatter

The following file can be used to configure the Eclipse formatter to follow the Google guidelines:

• eclipse-java-google-style.xml

Additional Style Requirements

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 rather than s; grade rather than grd. Variable names should balance clarity with brevity. The name person is better than currentPersonObject. However, per is worse than either (percentage? person? 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 (such as a TA). You should either include this statement in all files or minimally it may appear in the file containing your main method.

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

OR

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

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

Miscellaneous

• Normally, methods that return a value should have a single return statement.
• Avoid "magic numbers". Use named constants instead of literal values when you need to specify a constant value in your code. (e.g. Math.PI rather than 3.14159)
• Your code must not have unused variables or unnecessary statements (statements that do nothing).
• Avoid the use of break and continue except in switch statements.
• All instance variables should be declared private or protected unless there is a documented reason for not doing so.
• All visibility modifiers should be explicitly stated.
• Methods should not have undocumented side-effects. For example, print statements used for debugging should not be included in submitted code.
• Unnecessary code repetition should be avoided. Create helper methods where they will simplify your implementation.

---