Introduction to Programming (CPSC 124)
—Hobart & William Smith Colleges, Fall 2014
Programming Style
Home | Syllabus | Calendar | Class Notes | Labs and Projects | General Notes

Write clear, correct, and beautiful code.

Formatting

Your code should be formatted to maximize readability. The basic principle to follow is that logical blocks should be clearly identifiable and viewable on the screen, without scrolling, with clear visual separation from other logical blocks.

Comments

Comments - a.k.a. "internal documentation" - are an essential component of programming, even though they are not themselves executable, providing readers (including the programmer) with information necessary to understand a program. The general idea is to add a comment for each logical section of a program.

Your programs should include the following 3 ½ kinds of comments:

  1. File header comment. Every source code file should begin with a multiline comment of the following form:

    /*
    **  name of the file
    **
    **  Author:  your name
    **  internal title (e.g.  "CPSC 124, Assignment 1")
    **
    **  Summary: (Add a description of your program's use and behavior here)
    **  
    **  Created:  the date of creation
    **  Last modified:  the date of most recent modification
    */
    

    You are free to do more attractive ASCII art, so long as you keep the required information.

  2. Comments that document the main logical steps. Such comments should summarize what we know about the values of variables so far, and what the current logical step will accomplish. They should be no more than 2 or 3 lines (the fewer the better). In some cases, you can get away with only a trailing comment at the end of a single line.

    1. End-of-block markers. It is often helpful to add a comment after a closing brace, saying what block that brace closes. For example,
      public class Sqrt {
          public static void main(String[] args) {
              double x = Double.parseDouble(args[0]);
                  
              double sqX = 22.3; // "guess"
              
              while (!(Math.abs(sqX*sqX - x) < 0.0000000001)) {
                  sqX = (sqX + (x / sqX)) / 2.0;
                  
              } // while
              
              System.out.print("sqrt(" + x + ") is  "+ sqX);
              System.out.println("Math.sqrt:  " + Math.sqrt(x));
          } // main
      } // class Sqrt
      
  3. Method contract comments [We'll address this topic in a couple of weeks]. Every method (except for perfectly obvious ones) should begin with a multiline comment of the following form:

    /*
        SUMMARY: a brief description of what the method does, and what sort
           of information it returns (if any).
        PRE-CONDITIONS: A statement of the preconditions necessary for  
           correct execution
        SIDE-EFFECTS: A description of any changes that will be visible after
           the method returns
    */
    

Naming conventions (for variables, methods, classes, and packages)

Elegance

A good computer program is not only functional, but beautiful in its design. To borrow from Salieri, "Remove even one line, add even a single expression, and the whole edifice would tumble." Less dramatically, you should strive for programs that contain exactly the statements needed to produce a correct program, with source code that is easy for others to read, maintain, and perhaps expand.

This is the most subjective requirement, but there are a few hard and fast rules:


John H. E. Lasseter