Skip to main content
more options

Programming Style

Why you need to have style

The major reason for using a disciplined style of programming is to save you time when dealing with your programs. It will be much easier to find and correct the errors in your program if it is readable. Here we give some guidelines and conventions for programming. Following these guidelines will reduce the time spent programming and, more importantly, the time spent testing and debugging because fewer bugs will be introduced into programs.

  • Guideline 1. Specify a program segment before developing it.
    Do not try to solve a problem until you know what the problem is. To help you know what you are trying to do, it is important to write a clear and precise specification for a method before writing the method body. You also should use statement-comments (see below) to make code appear short and manageable. See Gries/Gries, pp. 376–380.
  • Guideline 2. Define variables.
    Write down the meaning of a variable before you use it. Then, when you work with the variable, make sure that the program keeps values consistent with the definitions (which you wrote in the first place) while making progress in the calculation. See Gries/Gries, pp. 381–384.
  • Guideline 3. Keep documentation and program consistent.
    Change the method specification before changing the method body. Similarly, change a variable definition, then the statements that use it.

Naming conventions (Gries/Gries, pp. 370–372)

Variables, methods, classes, and packages all have different naming conventions, although they share the main principle. We talk about them briefly and add some important points of differences.   

Conventions for variable names

  1. A variable name should consist of small letters, except that all “words” within it (except the first) are capitalized. This convention is almost universally used, e.g. isSmaller, colorOfDog.
  2. Do not use a long mnemonic name as a substitute for a careful definition of a variable in a comment.
  3. Make the length of a variable name proportional to the size of its scope. Local variables have the smallest scope, then parameters, then instance and static variables.

There are a few exceptions. For example, for naming constants, use all capital letters and use the underline character “_” to separate words within a name, e.g. MAX_VALUE.

Conventions for naming methods

The conventions here are similar to the ones for variables. A method name can be the name of algorithm used to do something or to compute the result. Procedure names are often commands to do something, while function names are noun phrases that describe the result.

Conventions for class names

  1. Use a noun phrase for the name —a list of adjectives followed by a noun— that describes an instance of the class. Capitalize each word in the noun phrase.
  2. If the class is generally not instantiated, perhaps because it consists mainly of static methods, then do not use convention 1, e.g. class Math contains only static components.

Conventions for indentation (Gries/Gries, pp. 373–376)

Indentation is used to help expose the structure of a program. Your program will be easy to read and also debug if it is well indented. Use four spaces for indentation; two spaces is not enough. We suggest changing a preference in DrJava so that a tab results in 4 spaces.

  1. In a sequence of constructs —variable declarations, method definitions, statements, and the like— all the constructs are indented the same amount.
  2. If a Java construct requires more than one line, its subconstructs that appear after the first line are indented.

We provide a few example of indenting.

if (…) {
     System.out.println(x);
     System.out.println(y);
} else {
     System.out.println(z);
}

// { x = A and y = B for some values A and B }
int t= x;
x= y;
y= t;
// { x = B and y = A }

Guidelines for writing methods (Gries/Gries, pp. 378–379)

  1. The specification must be consistent with the method body. It must explain precisely what the method does. If the spec and body have to change, change the spec first.
  2. Use a statement-comment to say what the Java code does.

Describing variables (Gries/Gries, pp. 381–384)

To describe variables, make sure that the description is clear so that one understands what the variables mean and give constraints on them. You can also group logically related variables together and describe them with one comment.

Statement-comments (Gries/Gries, pp. 379–380)

Suppose a program segment consists of three "statements", as show below, where we make explicit only the second statement.

(1) First statement;
    Permute x, y, z so that x <= y <= z
    Third statement;

When replacing the second statement by its implementation, we make the second statement into a comment:

(2) First statement;
    // Permute x, y, z so that x <= y <= z;
       Swap the largest of x, y, z into z;
          Swap the larger of x and y into y;
    Third statement

We can read (2) in two different ways. First, ignoring the indented swap statements, we can read it as we do (1), getting a good understanding of what the program is doing on a high level. Second, we can look at the two indented swap statements to understand how the permute-statement is implemented.

In (2), the comment is called a statement-comment, because we view it as a statement, as part of the program, whose implementation appears indented underneath it.

We can implement the two swap statements and present their implementation in the same fashion:

(3) First statement;
    // Permute x, y, z so that x <= y <= z;
       // Swap the largest of x, y, z into z;
                  if (x > z)
             {int tmp1= x; x= z; z= tmp1;}
           if (y > z)
             {int tmp2= y; y= z; z= tmp2;}
          // Swap the larger of x and y into y;
           if (x > y)
             {int tmp3= x; x= y; y= tmp3;}
    Third statement

Statement-comments are an important tool in presenting a program, because, as can be seen, they help the reader focus on one aspect of the program at a time. For example, we can read (3) in three ways: first, we can look at the high level sequence of three statements; second, we can look at the implementation of the permute statement as two swap statements, and third, we can look at the implementations of each of the swap statements.

We urge you to watch the first lecture on page 7-6 of the ProgramLive CD in order to see how statement-comments can be used to remove the idea of nested loops.

We have indented the implementations of statement-comments in order to make it easy to see the structure of the program segment. The field of computing generally does not do this, making it more difficult to see the structure. For example, below, we present (3) but without such indentation, and we try to use blank lines to make the structure clear. But this is difficult here because there are three levels. For example, it is not clear what the implementation of the permute statement-comment is.

(4) First statement;

    // Permute x, y, z so that x <= y <= z;
    // Swap the largest of x, y, z into z;
        if (x > z)
        {int tmp1= x; x= z; z= tmp1;}
    if (y > z)
        {int tmp2= y; y= z; z= tmp2;}
       

    // Swap the larger of x and y into y;
    if (x > y)
        {int tmp3= x; x= y; y= tmp3;}

    Third statement