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:

Guidelines

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:

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.

Program Grading

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

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:

  1. 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).
  2. 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.
  3. 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.)
  4. 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.
  5. 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)