Java Style and Documentation Guide

Coding conventions are guidelines for writing, organizing, and documenting source code. Such conventions may be created for a particular software development team, a project, an entire company, or the general community of programmers. The goal in every case is to enhance clarity, which reduces the cost of maintaining, modifying, and extending the software. According to the conventions developed by Sun Microsystems:

• 80% of the lifetime cost of software goes to maintenence.
• Software is almost never maintained for its whole life by the original author.
• Coding conventions improve the readability of software, allowing engineers to understand previously written code more quickly and thoroughly.

In your submitted work for this course, always follow the conventions that we practice in class for making your code look as neat and professional as possible. The easier to read and understand your work is, the higher your grade is likely to be. Some of the most important conventions are listed below.

A.   Naming

1. An identifier name should describe its purpose, except for routine local variables whose purpose is obvious (such as loop counters).
2. Use lowercase letters in the names of variables and methods, except to separate words (like dayOfWeek).
3. Class names are always capitalized nouns.
4. Method names are always verbs.
5. Always use named constants instead of magic numbers (except in trivial cases such as when 0 or 1 is used to initialize a loop counter).
6. Constant names are UPPERCASE, with an UNDER_SCORE to separate words.
7. If the purpose of a variable is not obvious from its name, then a comment is needed to explain its purpose.

B.   Indentation and Whitespace

1. Use 3 or 4 spaces for each level of indentation (you can set the tab spacing in your editor).
2. Leave a space before and after every binary operator.
3. Leave a blank line after every method and constructor.
4. Use blank lines to separate parts of a method that are logically distinct.
5. Avoid code drift: each line should be at most 80 characters long.
6. Consistently indent all statements appearing within a block to clarify the logic and flow of control.
7. Line up closing braces of blocks with the keyword owning the block.
8. There should be no more than two consecutive blank lines.

C.   Documentation

1. Each class must begin with a proper Javadoc comment including the purpose of the class and the author's name (first and last).
2. Each method and constructor must be preceded by a proper Javadoc comment with param and return tags as needed.
3. Within a method, comments are needed to explain any code whose purpose is not obvious.
4. Write a comment to explain the purpose of a variable unless the purpose is obvious from the name.
5. Document all known errors and deficiencies. This makes your code look more professional. It is also a form of intellectual honesty.

D.   Miscellaneous

1. Remove useless IDE-generated comments. They look unprofessional.
2. Remove typos and grammatical errors from output and documentation. They look unprofessional.
3. Methods should not be longer than about 30 lines, and usually not longer than 20. Implement utility methods for subtasks.
4. Class members should be ordered as follows: class variables, instance variables, constructors, methods.