Department of Mathematical and Digital Sciences
Bloomsburg University of Pennsylvania
Java Style and Documentation Guide
A style guide specifies conventions for writing and documenting source code. Complying with industry standards for style and documentation will make your code look as professional as possible. The most important standards observed in this course are listed below. For a more comprehensive list, see the Google Style Guide for Java. When evaluating coursework, I always begin by reading the documentation and studying the code before actually running and testing it. The easier it is to read and understand, the higher your grade is likely to be.
A. Naming
B. Documentation
C. Indentation and Whitespace
D. Miscellaneous
@Override annotation whenever applicable.a1. This rule may be relaxed if a variable's use spans only a few lines of code and it has an obvious purpose.
a3.
Methods are actions, so verbs or verb phrases are usually appropriate for naming
them. But sometimes a noun or noun-phrase describing the value or object returned
by the method is OK. For example, a method that returns the average of a given set
of values could be called getAverage or just average.
The Java API is not consistent on this point: witness, for example, the
Math method sqrt vs. the
LocalDate method getDayOfYear.
a4. Classes represent abstract entities, things, like a scanner or a string, so nouns and noun phrases are typically used to name them.
b1.
The doc comment for a class must include at least a summary fragment and
the @author tag (with author's full name) separated by an empty line.
A summary fragment begins with an action verb (calculates, creates,
finds, returns, etc.) and expresses the purpose of the class or
program in general terms. It is capitalized and punctuated as if it were a
complete English sentence.
/**
* Prompts the user for a string and outputs the longest substring that starts
* and ends with the same character.
*
* @author Drue Coles
*/
|
Additional details can be provided in a separate paragraph after the summary fragment.
/**
* Prompts the user for a string and outputs the longest substring that starts
* and ends with the same character.
*
* For example, if the user enters SALAMANDER then the program outputs ALAMA.
* If there is more than one possible result, the program outputs the first
* one from the left (for example, QUEUE -> UEU).
*
* @author Drue Coles
*/
|
Important: the doc comment for a class must also include a full account of any bugs, gaps, or missing features. This account should provide an accurate description of what to expect when your code is executed. Your grade will be higher for properly documenting problems instead of leaving them for me to discover on my own. Describe conditions that lead to incorrect behavior and explain what happens under those conditions. Be as specific as possible and give examples if that might help to diagnose the problem. For example:
/**
* Prompts the user for a string and outputs the longest substring that starts
* and ends with the same character.
*
* For example, if the user enters SALAMANDER then the program outputs ALAMA.
* If there is more than one possible result, the program outputs the first
* one from the left (for example, QUEUE -> UEU).
*
* KNOWN BUGS:
*
* 1. The program does not output the correct substring when it is at the end
* of the user's input. For example, if the user enters LIGHTNING, the program
* outputs IGHTNI (6 characters) instead of GHTNING (7 characters).
*
* 2. If the user enters a single character, the program throws an exception.
*
* @author Drue Coles
*/
|
b2.
A method's doc comment requires at least a summary fragment. Use a
@param tag to document any parameter whose meaning is not clear. You
can use the @return tag to explain what the method returns, unless
this is already obvious from the name of the method and/or the summary fragment.
If your IDE generates these tags automatically and they are not needed, remove
them.
b5. Examples of comments that serve no purpose:
// stores the sum
int sum = 0;
// outputs the result
System.out.println(result);
|
b6. There is no need to tell the reader that you are, say, declaring variables, doing some arithmetic, or writing a loop. The reader can see that. Remember, you are writing for the benefit of any competent Java programmer, so there is no need to explain general programming concepts or features of the language. What needs explaining is the meaning and purpose of each block or other logical unit of code (if not already obvious).
c2. The opening brace for a block is placed on the same line as the block's header, and the closing brace is always on a line by itself at the same level of indentation as the header.
public static void main(String[] args) {
int x = 0;
while (⋯) {
if (⋯) {
⋯
} else {
⋯
}
}
System.out.println(x);
}
|
c3. Examples:
// bad
int x=offset+width/cols;
System.out.println(month+"/"+day+"/"+year);
// good
int x = offset + width / cols;
System.out.println(month + "/" + day + "/" + year);
|
c6. This ensures that the source code can be read without having to scroll horizontally. It also enables printing on paper without clipping at the right margin.