6.170 / Spring 2000 / Java Style Guide
Handout 3
Overview
Coding style is an important part of good software engineering practice.
The goal is to write code that is clear and easy to understand, reducing
the effort required to make future extensions or modifications.
Many aspects of code help make it readable. Some of the most important
are descriptive names, consistent indentation, and informative comments.
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.
Descriptive names
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.
A common convention that we recommend you follow is to capitalize names
of classes, but start variable and package names with a lower case letter.
There are other common conventions, such as naming constants using all
uppercase letters; we do not require you to follow any particular conventions,
but you should choose those that you find helpful and follow them consistently.
Consistent indentation
Indenting code consistently helps the reader understand the logical structure
of your code by making 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.
Emacs provides an autoindent mode. You should use it to format
your code as you type it, and reformat it after you have changed it. You
can also use grind to format your code nicely for printing even
if the source file is not well indented.
Informative comments
Don't make the mistake of writing comments everywhere -- a bad or useless
comment is worse than no comment. If information is obvious from the code,
adding a comment merely creates extra work for the reader.
i++; // increment i THIS IS A USELESS COMMENT
Good comments add information to the code in a concise and clear way. For
example, comments are informative if they:
-
Enable the reader to avoid reading some code. The following comment
saves the reader the effort of figuring out the effect of some complicated
formulas, and states the programmer's intention so the formulas can be
checked later on.
// 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.
Explain an obscure step or algorithm. This is especially important
when the effects of some step are not immediately obvious in the code itself.
You should explain tricky algorithms, operations with side effects, magic
numbers in the code, etc.
// 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 ++;
Record assumptions. Under what assumptions does a piece of code
work properly?
// 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();
Record limitations and incomplete code. Frequently the first version
of code is not complete; it is important to record which code is known
to be incorrect. If you run out of time on an assignment and turn in a
program that does not function correctly on all inputs, we will expect
your code to show that you understand its limitations.
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;
}
Hints:
-
Don't write code first and then comment it -- comment it as you go along.
You are unlikely to go back and do it later.
-
We do not require you to write comments on every program object as is done
in some software engineering courses. However, your grade depends substantially
on the clarity of your code, and some piece of the program that seems clear
to you may not be clear to the reader. Therefore, it may be to your advantage
to add explanatory comments to all classes, fields, and methods.