Coding, Documentation, and Style Guidelines

Readability is an important part of programming. For a program to be easy to understand, it should follow certain guidelines. Style is not universally true, since different people use different strategies, but many style issues are consistent. These should always be followed.

General

  • Be consistent
  • Avoid clever tricks that are difficult to follow
  • Use descriptive names for everything, e.g., variables, constants, functions/subroutines, etc.
  • Always us "Option Explicit" to force explicit variable declarations
  • Use indentation to show code blocks such as the inside of loops, inside of if-then statements, inside a function/subroutine, etc.
  • Use space liberally, yet sensibly, to make your code readable. Typically there are spaces surrounding operators such as =, +, etc.
  • Limit your code and comments to 80 characters per line. This is so code or comments do NOT wrap when printed on standard 8.5 by 11 inch paper in portrait mode.
  • Always print code in portrait mode on standard 8.5 by 11 inch paper.

    Functions/Subroutines
  • Each routine method should perform a single well-defined operation. If your routine accomplishes two tasks, break it in two routines. This improves the modularity of the code.
  • Use a blank line (and comments) before functions/subroutines and within functions/subroutines to delineate logical code blocks
  • At the beginning of each file describe what the file contains. Give the author name and a brief description of how the code is used.
  • For each routine, include a brief description of the purpose and what assumptions are made (if any). Include pre-conditions and post-conditions (including input and output) when it helps to clarify the function.
  • Use additional comments to describe each block of code within a routine, but typically there are not comments on every line of code.