-- Cornell Professors William Strunk and E.B. White, The Elements of Style

• Introduction
• Reasons for following a disciplined programming style
• Naming conventions
• Classes
• Methods
• Parameters
• Fields
• Local variables
• Constants
• Indentation
• Specifications and comments
• Classes
• Methods
• Variables
• Statements
• Acknowledgements

A goal of CS99 is for you to learn to write programs that are not only correct but also understandable. These guidelines should help you toward that goal. We ask that you follow these guidelines when writing programs in this course. They will give you a good basis for developing a style of your own as you become a more experienced programmer.

This handout includes guidelines for Java constructs that will be covered later in the semester. Skim these sections now and read them more carefully later when the topics are discussed.

 Many of the remarks in this handout follow from these two underlying principles:

• Simplicity
• Clarity

The major reason for using a disciplined style of programming is that it will save you time whenever you have to read your program or debug it.

Outside this course, making programs readable by others becomes even more important. Most programs live a long time and require "maintenance" - changes to adapt to new and different requirements, upgrades in other software, new hardware, etc. And the author of the program is quite likely not going to be around when the maintenance is required; someone else must read the program and understand it enough to update it successfully.

Even the programs you write for yourself should be readable; if not, four weeks after finishing it you will not remember it enough to make changes simply. Thus, simply for your own sake and for the sake of others, it makes sense to develop programming habits that lend themselves to writing readable, understandable, and correct, programs.

Part of these habits concern simple, syntactical measures like indenting program parts properly and using a few conventions for names of variables, methods, etc. The more important part concerns recording enough information in comments for the reader to understand how a program is designed and why.
 

Remember that a name can rarely be used to give a complete, precise definition of the entity it names, and a complete definition should always be given where the entity is defined.

The people developing Java programs have developed some conventions for identifiers, which help one readily see what the identifier represents (to some extent). You can see these conventions at work by looking at the classes in java.awt (Abstract Window Toolkit). Below, we state the conventions, with a few additions.
 

Substatements of a statement or declaration should be indented.

Indenting is usually done with the TAB key, although several modern editors will automatically produce proper indentation. A standard amount to indent is 4 spaces.

There are several methods for placing curly braces that delimit statements, none of which is liked by all and all of which are disliked by some. Below, we illustrate three methods, with pros and cons explained to the right. It is common to see (1) used in C and C++, and (2) used in Java.

(1) if (x < y)      Pro: It is easy to match up braces
    {               Con: Too many lines are used, and the
        x = y;           number of lines is a scarce re-
        y = 0;           source on the monitor.
    }               Con: The substatement {x = y; y = 0;} has
    else                 not been indented, because the
    {                    braces are part of the substatement.
        x = 0;           Therefore, the basic rule concerning
        y = y/2;         indentation has not been followed.
    }
(2) if (x < y) {    Pro: There are no wasted lines.
        x = y;      Pro: The opening brace is out of the way
        y = 0;           and the closing brace indicates
    } else {             nicely the end of a substatement
        x = 0;      Con: It is difficult to match up be-
        y = y/2;         ginning and end braces.
    }
(3) if (x < y)      Pro: There are no wasted lines.
        {x = y;     Pro: The basic indentation rule is followed.
        y = 0;      Pro: It is easy to match up beginning and
        }                end braces and easy to see where a
    else                 substatement ends.
        {x = 0;     Con: The first statement of a substatement
        y = y/2;         indented differently from the rest.
        }

It doesn't matter which style you use, as long as you use it consistently throughout a program. When working on a program written by someone else, match their style.

Below, we illustrate two ways to place the curly braces surrounding the body of a method. There are others. Choose one and use it consistently within a program. Again, (1) is common in C/C++, and (2) is common in Java.

(1) // Specification of method
    void drawLine(int x1, int y1, int x2, int y2)
    {
        statement 1;
        statement 2;
    }
(2) // Specification of method
    void drawLine(int x1, int y1, int x2, int y2) {
        statement 1;
        statement 2;
    }

Another issue is whether braces should be places around a single statement used as the body of a loop or a conditional. Although there is no generally-held correct answer to this question, it is always safer to use the braces. It will save you from making many errors. So get in the habit early of writing:

if (month == FEB) {
    if (year%4 == 0) {
        if (day > 29) {
            legal = false;
        }
    } else {
        if (day > 28) {
            legal = false;
        }
    }
}

instead of:

if (month == FEB) {
    if (year%4 == 0) 
        if (day > 29) 
            legal = false;
    else
        if (day > 28)
            legal = false;
}

which actually won't work anyway, because of something called the "dangling else" ambiguity.  (Which "if" is the "else" attached to?  Hint: it's NOT the "if (year%4...".)
 

So, it will be to your advantage to instill in yourself some disciplined programming habits, right from the beginning, like:

• Write a precise definition (in a comment) of a variable as you write its declaration
• Update the definition of the variable (the comment) when you decide to change its meaning
• Write a precise specification for a method (which says what it does) as you write the method's heading - don't wait until after the method is completely written or until the program is debugged.
• Change the specification for a method whenever you make changes to the body of the method that make the body not fit the specification.

1. The comments were not of use to you when developing and debugging the program, so you took more time than was necessary.
2. The comments are harder to write after the program is finished, because it is difficult to remember the meaning of all the variables and methods.
3. It is quite likely that you won't write the comments - even programmers with the best intentions don't spend much time filling in comments after the fact, because there are too many other interesting things to do.

 The Elements of Style contains several rules that are useful for programming as well as writing. Among them are:

• Omit needless words.
• Use the active voice.

// Yield "y is in list x" boolean isIn(int y, List x)

Similarly, don't belabor the obvious. Comments shouldn't repeat the code, such as "increment j" does for j++. Neither should comments contradict the code. So when you change code, change the comment!

Use comments to clarify code, not confuse it. If you find a comment growing longer than the code itself, it is probably the case that either the comment is too long or the code is bad and needs rewritten. The best way to rewrite such code is to make is self-documenting. This can be done through the choice of good variable names and the use of idiomatic statements.
 

Classes

//An object of class Auto represents a car.
//Author: John Doe.
//Date of last modification: 25 August 1998
public static class Car;

A more idiomatic expression of the same specification in Java would be:

/**
 * An object of class Auto represents a car.
 * @author John Doe
 * @modified 25 August 1998
 */
public static class Car;

Methods

Here is an example.

/**
 * Print on System.out the most frequently occurring temperature
 * in t[0..c-1]. If there is more than one possibility, print
 * the least temperature.
 */
void printCommon(Temperature[] t, int c)

Unfortunately, it is more typical to find a comment like the following (if any comment is provided at all).

/**
 * Print most frequent temperature
 */
void printCommon(Temperature[] t, int c)

This specification fails to say what part of array t is to be included in finding the most frequent temperature. It also fails to say where to print, which will be a problem if there is more than one possibility. The only way for the user to find out is to look at the body of the method (if it is available), and that should not be necessary.

For a function -- i.e. a method that returns a value -- it is often easiest to simply describe the value returned, using the word "yield":

/**
 * Yield distance between points (x1,y1) and (x2,y2)
 */
double dist (int x1, int y1, int x2, int y2)

Variables

Important hint: Write the definition of a set of variables when you first conceive of using them, and type the definitions as comments into the program when you type in the declarations of the variables. If you later decide to change the meanings of the variables, change the definitions before you change the statement that use the variables.

Here is an example of a definition for two variables i and currentItem --they are defined in a single comment because they are related.

// 0 <= i <= currentItem < numberItems and i is the smallest value
// such that item i's price is at most item currentItem's price.

The definition for a boolean variable is usually best presented as the value of some English (or mathematical) statement. For example, the following two definitions are equivalent, but the first is shorter.

boolean b; // = " user selected menu item File | Quit"
boolean b; // true if the user selected menu item File | Quit;
           // false otherwise

The more precise a definition, the better. Comments like "flag for loop" or "index into b" are useless; they only say how the variable is used, but not what it means.

Related variables should be declared and described together. For example, the definition of a table should describe not only the array that holds the data but also the integer variable that contains the number of items currently in the table. In the example below, for utmost clarity tabs are used to line up identifier names and to line up the comments.

final int maxTemp = 150; // max number of temperature readings.
int nTemp = 0;           // Temperature readings are in
                         // temp[0..nTemp-1], where
                         // 0 <= nTemp < maxTemp
double temps = new double[maxTemp];

If the comment is too long to fit nicely on the right (as is the case above), then put it above the declarations.

// Temperature readings are in temp[0..nTemp-1], where
// 0 <= nTemp <= maxTemp and maxTemp is the maximum number of
// temperature readings final int maxTemp = 150;
int nTemp = 0;
double temps = new double[maxTemp]

Finally, it is idiomatic in Java to use javadoc-style comments rather than double-slash-style comments when defining class variables (fields). Double-slash-style comments should still be used for local variables.

class List {
    /**
     * Maximum size of list
     */
    static final int maxSize = 100;
}

Statements

 The comment for such a logical unit is called a "statement-comment". It should be written as a command to do something. Here is an example.

// Truthify x >= y by swapping x and y if needed.
if (x < y) {
    int tmp = x;
    x = y;
    y = tmp;
}

The comment should explain what the group of statements does, not how it does it. Thus, it serves the same purpose as the specification of a method: it allows one to skip the reading of the statements of the logical unit and just read the comment. With suitable statement-comments in the body of a method, one can read the method at several "levels of abstraction", which helps one scan a program quickly to find a section of current interest, much like one scans section and subsection headings in an article or book. But this purpose is served only if statement-comments are precise.

Statement comments must be complete. The comment

// Test for valid input

is not adequate. What happens if the input is valid? What if it isn't -- is an error message written or is some flag set? Without this information, one must read the statements for which this statement-comment is a specification, and the whole purpose of the statement comment is lost.

Placement of statement-comments

// Truthify the definition of t -- return false if not possible

    // Eliminate whitespace from the beginning and end of t
    while (t.length() != 0 && isWhitespace(t.charAt(0)))
        t= t.substring(1);

    // If t is empty, print an error message and return
    if (t.length() == 0) {
        ...
        return false;
    }

    if (containsCapitals(t)) {
        ...
    }

// Store the French translation of t in tFrench
    ...

At the highest level, the program fragment consists of two statements: (1) Truthify the definition t and (2) Store the French translation of t in tFrench. The statement "Truthify the definition of t" is implemented in three steps, two of which are themselves statement-comments. Thus, this program fragment has three levels of abstraction.

 In this example, note how reliance on the definition of t in the statement-comment "Truthify the definition of t" allows the statement-comment to be short but precise. Of course, a suitable definition for t must appear at its declaration.

 Many people prefer not to indent substatements of a statement-comment and to rely on blank lines to separate the end of the substatements of a statement-comments. Below, we show the above program fragment in this style. Note the extra comment to help the reader see the end of the substatements for "truthify the definition of t". This style is has its problems. If you decide to use this style, then program in such a way that statement-comments do not appear within statement-comments, so that such awkwardness does not arise. Modularizing into separate functions is one way to do this.

 // Truthify the definition of t --return false if not possible

// Eliminate whitespace from the beginning and end of t
while (t.length() != 0 && isWhitespace(t.charAt(0))) {
    t= t.substring(1);
}

// If t is empty, print an error message and return
if (t.length() == 0) {
    ...
    return false;
}

if (containsCapitals(t)) {
    ...
}

// (End of Truthify the definition of t)

// Store the French translation of t in tFrench