Below you will find an itemized list of comments that I use when grading your code that address issues of programming style. What follows for each comment is a description of the style issue, how to handle it properly, and both a negative and positive example.
Note that there is no single style that can be considered the "best". However, the recommendations presented here are for one style that is commonly considered good and, critically, easy for me to read. You may deviate from these recommendations only if you have a specific motivation and an alternate approach that I reasonably consider to be equally, aesthetically satisfying.
Keep lines short: 80 characters or fewer. Trying `M-x auto-fill-mode' to make XEmacs do it for you.
Keep method call spacing consistent: When calling a method, either put a space between the method name and the opening parenthesis of the argument list or don't. Be consistent. For the arguments, consistently use a spaces in separating arguments and commas. For example:
NO: foobar (x ,y, 15 , "Blah" );
YES: foobar(x, y, 15, "Blah");
Use spacing around operators: Visually separate each operator from the data on which it operates. Most of all, use the spacing consistently. For example:
NO: boolean b= (x<y +3);
YES: boolean b = (x < y + 3);
Use vertical spacing: Between logical `chunks' of code, put a blank line. A good rule of thumb here is that every comment in your code should be preceeded by a blank line. Also, if the body of a conditional statement (if-then-else) or a loop contains more than one or two lines, put a blank line on either side of the body, within the braces. For example:
NO:
while (doodle != noodle) {
// Set some values
int x = 1;
int y = x * 15 + 3 / noodle;
// Ask a question
System.out.print("Enter a baaz: ");
char c = Keyboard.readChar();
}
YES:
while (doodle != noodle) {
// Set some values
int x = 1;
int y = x * 15 + 3 / noodle;
// Ask a question
System.out.print("Enter a baaz: ");
char c = Keyboard.readChar();
}
Use indentation consistently: Be sure that *all* of your code is carefully indented. Remember that within a pair of curly braces (`{' and `}'), the text should all be indented one additional stop (4 spaces). Also, a closing curly brace should indent to the same depth as the line on which its corresponding opening brace appears. For example:
NO:
if (quux < 15) {
System.out.println("I'm so happy!");
} else {
System.out.println("The sadness is overwhelming...");
}
YES:
if (quux < 15) {
System.out.println("I'm so happy!");
} else {
System.out.println("The sadness is overwhelming...");
}
Comments should preceed the lines to which they refer: Make sure that you describe, in comments, what you code does. These comments should preceed the block of code described. Do not place comments after the block of code, and do not place comments on the same line as code. There is one exception to this last rule: you may place a comment on the same line as the closing brace of a method, indicating that the method is complete. Finally, comments should be complete, grammatical sentences. For example:
NO:
double r = 1.0;
for (int i = 0; i < y; i++) { // Count from 0 to y
r = r * x; // Multiply by x
}
//multiply x y times.
YES:
// Calculate x^y by performing the y multiplications of x.
double r = 1.0;
for (int i = 0; i < y; i++) {
r = r * x;
}