In 6.170 we do not specify a detailed coding style that you must follow. However we expect your code to be clear and easy to understand. This handout provides overall guidelines within which you should develop your own effective coding style.
Names for packages, types, variables, and branch labels should document their meaning and/or use. This does not mean that names need to be very long. For example, names like i and j are fine for indexes in short loops, since programmers understand the meanings and uses of these variables by convention.
You should follow the standard Java convention of capitalizing names of classes, but starting method, field, variable, and package names with a lower case letter. Constants are named using all uppercase letters. The Java Language Specification provides some common Naming Conventions that you may want to use when naming your classes, methods, etc.
Indenting code consistently makes it easy to see where if statements and while loops end, etc. You should choose consistent strategies; for example, be consistent about whether you put the open curly brace on the same line as the if or on the next line, or what your try-catch-finally blocks looks like. Examine the code in the textbook for a sample style; feel free to develop your own if it makes you more comfortable.
In Emacs's Java mode, return indents the next line to (its guess at) the correct column, and the tab key re-indents the current line. There are also commands for re-indenting an entire region of lines.
Consistent (and adequate) spacing also helps the reader. There is no reason to try to jam your code into as few columns as possible. You should leave a space after the comma that separates method arguments. You should leave a space between for, if, or while and the following open parenthesis; otherwise, the statement looks too much like a method call, which is confusing. In general, you should place only one statement on each line.
i++; // increment
Good
comments add information to the code in a concise and clear way. For
example, comments are informative if they:
// Compute the standard deviation of list elements that are
// less than the cutoff value.
for (int i=0; i<n; i++) {
// ...
}
An important application of this type of comment is to document the
arguments and return values of functions so clients need not read the
implementation to understand how to use the function.
// Signal that a new transfer request is complete and ready
// to process. The manager thread will begin the disk transfer
// the next time it wakes up and notices that this variable has changed.
buffer_manager.active_requests ++;
// The buffer contains at least one character.
// (If the buffer is empty, the interrupt handler returns without
// invoking this function.)
c = buffer.get_next_character();
Whenever you use a generic container (such as Vector,
ArrayList, or Tree) you should always indicate with a
comment the types of the elements. Either of the following formats is
acceptable; the second is suggestive of the
List<RatTerm> syntax that will be used in Java 1.5 to
indicate the element type.
private List terms1; // elements are RatTerm objects
private List/*<RatTerm>*/ terms2;
if (n > 0) {
average = sum / n;
} else {
// XXX Need to use decayed average from previous iteration.
// For now, just use an arbitrary value.
average = 15;
}