Appendix B: Writing Clear Code


The overarching goal when writing code is to make it easy to read and to understand. Well-written programs are easier to debug, easier to maintain, and have fewer errors. Writing a program is a lot like writing an essay. When writing an essay, your message is more convincing when it is accompanied by proper grammar and punctuation. When writing computer programs, you should follow the same principle. It is even more important when programming since someone may be assigned to maintain and support your code for long periods of time. You will appreciate the importance of good style when it is your task to understand and maintain someone else's code!

Coding.


Naming conventions.

Here are some general principles when choosing names for your variables, methods, and classes.

IDENTIFIER NAMING RULES EXAMPLE
Variables A short, but meaningful, name that communicates to the casual observer what the variable represents, rather than how it is used. Begin with a lowercase letter and use camel case (mixed case, starting with lower case). mass
hourlyWage
isPrime
Constant Use all capital letters and separate internal words with the underscore character. N
BOLTZMANN
MAX_HEIGHT
Class A noun that communicates what the class represents. Begin with an uppercase letter and use camel case for internal words. class Complex
class Charge
class PhoneNumber
Method A verb that communicates what the method does. Begin with a lowercase letter and use camelCase for internal words. move()
draw()
enqueue()

Commenting.

Programmers use comments to annotate a program and help the reader (or grader) understand how and why your program works. As a general rule, the code explains to the computer and programmer what is being done; the comments explain to the programmer why it is being done. Comments can appear anywhere within a program where whitespace is allowed. The Java compiler ignores comments.

There is no widely agreed upon set of rules. Good programmers write code that documents itself.

Whitespace.

Programmers use whitespace in their code to make it easier to read.

Indenting.

Programmers format and indent their code to reveal structure, much like an outline.

Q + A

Q. Are there any official coding standards?

A. Here are Sun's Code Conventions for the Java Programming Language. However, this document was written in 1997 and is no longer being maintained.

Q. Any good references on programming style?

A. The Practice of Programming by Brian W. Kernighan and Rob Pike is a classic.

Q. Do Java comments nest?

A. No. So you cannot eliminate a block of code by simply surrounding it with the block comment delimiters (since the block itself may contain a */ delimiter).

Q. How can I autoindent my code?

A. Use an editor designed for writing code. For example, in DrJava, if you select a region of code and hit the Tab key, it will reindent it for you automatically.

Q. Are there tools for enforcing coding style?

A. Yes, we recommend Checkstyle. If you followed our Windows, Mac OS X, or Linux instructions, checkstyle will already be installer and set up to use our configuration file.

Q. How can I write unmaintainable code?

A. Here's one guide to designing unmaintainable code and here's another.

Exercises

  1. Fun with comments. What is the value of a after the following code fragment is executed?
    //*/
    a = 17;
    /*/
    a = -17;
    //*/
    
    Repeat the question after deleting the first /.
  2. More fun with comments. What does the following print?
    public static void main(String[] args) { 
       boolean nesting = true;
       /* /* */ nesting = false; // */ 
       System.out.println(nesting);
    } 
    

    Answer: this code prints true if /* comments can nest and false if they can't. Since Java comments don't nest, it prints false.