Handout S1: Java™ Style Guide
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.
Top