CS Department
Program Style Guide

Good programming style is an important feature of any good program. Gary Litvin of Skylight Software gives the following explanation on why a working program with poor programming style is not good enough:

First, a programmer's product is not an executable program but its source code. In the current environment the life expectancy of a "working" program is just a few months, sometimes weeks. On the other hand, source code, updated periodically, can live for years; to be of any use, it must be readable to others. Second, bad or unconventional style is uncool. It immediately gives away an amateur, a kind of social misfit in the software developers' culture. As nerdy as this culture might be, it has its own sense of esthetic pride. [from The 32 Bits of Style, http://www.concentric.net/~skylit/style]

This document describes basic style guidelines for use at Kalamazoo College. An excellent additional resource is: The Elements of Java Style by Vermeulen et al, which is described more fully at the end of this document.

Jump directly to:

General Guidelines
Internal and External Documentation
Program Format
Coding Style
Capitalization
Program Grading
Additional Style Guidelines

Guidelines

Structure, simplicity, and even neatness are crucial considerations for the production of working, high-quality programs.
For a program to be used, it must be well-organized, coherent, and easy to understand. Since real application programs are frequently modified, future users need to be able to read a program easily.
A well-written program reflects a well-conceived design; such a program is almost always simpler and more efficient than a hastily written or jumbled one.

Internal and External Documentation

Internal: See the Documentation Standards document for a description and example of program headers and for a description of internal code documentation.

External: In addition to the comments inside a program, you should create external documentation (e.g., a User's Guide, Help file, or man page) that gives the name of the program, directions for using it, a short description of the purpose of the program, your name, the date when you wrote the program, and dates and comments on any subsequent modifications you wrote. Here is one possible README.txt template you could use.

Program Format

Formatting refers to the way statements are placed in a program -- indentation, blank lines, etc. Good formatting can make a program far easier to understand.

White space is essential for clarity. This includes spaces around identifiers, operators, at the beginning and end of comments, as well as blank lines, especially to separate blocks and different sections of blocks.

Consistent indentation is essential for readability. Indentation should be used to indicate that the indented statements are under the control of the previous non-indented statement. Use this as a test when deciding to indent. Always indent inside the { } bracket pair. Examples in C, C++, or Java:

Inside a block:

        {
            statement 1;
            statement 2;
            etc.
        }

Inside a for or while or do while loop:

        for (k = 1; k < = maxSize; k++)
        {
            sum = sum + k;        // under the for's control
            sum2 = sum2 + k * k;
        }

With an if then else construct:

        if (k == 10)
            k = 0;
        else
            k++;

Coding Style

Keep statements reasonably short. Try to avoid statements that take more than one line. Keep the number of lines in a block down so that a block fits on one screen (about 21 lines), excluding initial documentation. Then the block can be scanned easily for content, coherence, use of variables, etc.

Choose names for your variables and other identifiers that are meaningful in the context of their use.

Avoid the use of constants within program statements. Rather, declare them as named constants so that a future user can change their values easily for different applications.

Capitalization

Here are the capitalization rules you are expected to use in your programs for homework, tests, and projects. Remember that many languages are case-sensitive.

In general, use lower case for class variables, instance variables, local variables, and parameters. The common exception is to use all capital letters for constants (e.g., Color.RED, Direction.NORTH, DEFAULT_CELL_SIZE). In C or C++, capitalize macro names and variables and constants of global scope (the entire name).
Capitalize the first letter of user-defined types, including class and interface names.
Within all identifiers, capitalize the first letter of each word embedded in the name, except for the first letter of the identifier as a whole. If the identifier is a class or interface name, the first letter is capitalized also (see above). For example, aLongName would be a valid name for a variable or parameter; ALongClassName would be a valid name for a class.
Acronyms are special cases. If the first letter of the acronym would be capitalized according to the rules above, capitalize the entire acronym. If the first letter would be lowercase, leave the entire acronym in lower case. For example, gpa, GPAClass, and studentGPA would all be valid names.

Program Grading

Your programs will be graded according to the following five components:

Program correctness: Each program should conform to specifications stated in the problem statement. A program should demonstrate correct handling of ordinary input, special cases, and error conditions. Test data should include typical values, out-of-range values, boundary values and special case values.
Program and class design: Your program should be modularized, and refactored as necessary, into small, coherent, independent functions, classes, or methods, with weak coupling and strong cohesion.
Style and documentation: Your program should be easy to read and understand. This involves program indentation, modular design, variable names, user interface and program comments. Pre-conditions and post-conditions should be documented wherever they apply. See the Documentation Standards document for more specific information about appropriate internal documentation for files, classes, and methods/functions.
Efficiency: Algorithms chosen should be efficient in regards to both time and space. Algorithms should be written cleanly and clearly rather than written using brute-force. You should be prepared to justify your choice of algorithms.
Test Cases: You should develop appropriate test cases when developing and testing your programs. For some programs, you may be asked to hand in your test cases and results along with your program.

Additional Style Guidelines

The Elements of Java Style, by Vermeulen et al and published by Cambridge University Press, presents a more detailed set of style guidelines, formatted as rules. Although the book's title and examples refer to Java, most of its guidelines can be applied to C, C++, and other languages. Most of the rules in The Elements of Java Style align with K's style conventions, with five notable exceptions:

Use 4 spaces rather than two, and put the left brace on its own line, lined up with the right brace (the Braces Line Up style pattern).
Blindly following the get/set method-naming conventions leads to methods that closely align with the internal data representation, violating the principle of Data Hiding. If you use the getAttribute style, be sure to think in terms of object attributes from the client's perspective, rather than the actual internal representation.
Again, Data Hiding implies that method and parameter names should align with the client code perspective, which might or might not correspond to the internal data representation. (This is the same concern as for Rule 24.)
The semi-colon indicating an empty statement should be on the next line and indented, just as a normal statement would be. This provides an extra visual clue that the statement associated with the control structure is empty. (Some compilers will even produce warnings when the semi-colon is on the same line but not when the semi-colon is on the next line, taking that as an indication of an intentional empty statement.
Although the principles and most of the specifics of this rule are valid, some of the strictures against overriding are misleadingly strong. The last example clarifies acceptable use.

Revision History: September 1993, September 1998, March 2008, April 2015 (added references to Vermeulen et al)

CS Department Program Style Guide