CS Department
Program Style Guide

Programming projects will consist, usually, of programs to be written by you. While you can and indeed should work with others on the design of a homework programming assignment, the implementation should be yours alone.

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]

Jump directly to:

• General Guidelines
• Documentation
• Program Format
• Coding Style
• Capitalization
• Program Grading

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.

Documentation

In addition to the comments inside a program, you should create a User's Guide which 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.

Program Format

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

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

• 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. All classes and methods should include javadoc-style documentation. Pre-conditions and post-conditions should be documented wherever they apply.

• 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.