Sample style rules for programming

Below we have a set of sample style guidelines for programming. Obviously there are many possible stylistic choices, the one below is purely used as an example.

Some of these will correspond closely with the lab standards used for this course, and you will find comparable patterns of rules you must adhere to in most software development organizations.

Having such guidelines makes it easier to read, comprehend, debug, and modify large programs written by a variety of developers over extended periods of time.

1. Define a common layout: this ensures you (and others) know where to look for the definitions of key program parts. For example, all source code files must follow the organization format shown below:
   1. User description
   2. Design description
   3. Header files (include statements)
   4. Other pre-processor directives (# statements)
   5. Global constant definitions
   6. Prototypes (function and type declarations)
   7. Main function body
   8. Other function bodies

2. Define subroutine size restrictions: no function or method, including main, should have more than 40 lines of code including comments and whitespace, and following the style rules listed below.

3. Define the minimum common files: Each executable should be accompanied (in the same directory) by a README.TXT file and a MAKEFILE, which should outline all actions necessary to created the desired executable and possible variations.

4. Define the development environment: development is to be carried out using one of the following packages/compilers:
   • The g++ compiler for Linux or Unix
   • MicroSoft Visual C++ .Net or Visual C++ 6.0 with service pack 5

5. Define the code layout/style:
   • Commenting: comments should be included to provide black box descriptions of each abstract data type, each function, and each variable. When commenting code, the following guidelines should be used (from Kernighan and Pike's "The Practice of Programming")
     • Don't belabor the obvious - i.e. don't just echo the code
     • Comment functions and global data - as per note above
     • Don't comment bad code, rewrite it - if code requires excessive explanatory comments it may be a sign the code is poorly written
     • Don't contradict the code - when code is changed make sure the commenting is changed to accurately reflect this
     • Clarify, don't confuse - don't add rambling, complex explanations
   • All code statements within a block (loop body, function body, if/else/switch statement) are to be indented 3 spaces
   • Align left (i.e. opening) brackets with the leftmost character of the preceeding line, and right (i.e. closing) brackets with the opening bracket they terminate, e.g.:

        for (iLoopIndx = 0; iLoopIndx < 10; iLoopIndx++)
        {
            if (iQuitFlag == 0) 
            {
                 ...
            }
        }
     

     When "single-stepping" through a program during debugging/execution, this format makes the program's actions clearer - we can tell by which lines are visited whether or not the if conditional evaluated to true or not.
   • For statements with a single executable line, always place the executable on the following line, indented three spaces, e.g.

     if (iQuitFlag == 1)
        break;
     

     Again, this format allows clearer interpretation of program actions when stepping through execution with a debugger.

6. Define the notaton for identifiers: (the style suggested here is often referred to in other references as Hungarian notation) variable and function names should not be cryptic - they should convey the role of the function or variable to anyone reading your code.
   • Example: the variable name x means nothing to those unfamiliar with your program, however the name lNumberofSteps clearly indicates that the variable is being used to record some number of steps.
   • Constants should be declared entirely in uppercase.
   • Variables should be prefixed with one or more characters indicating the variable type:

     u : unsigned integer l : long integer i : integer s : short integer d : double precision float f : floating point

     c : character z : string p : pointer g : global a : array e : enumerated type

   • To increase readability, capitalize the first letter of each word in a variable name, e.g. dToolCount. The use of underscores (except as noted below) is discouraged.
   • Function names and modules: when a program is divided into modules, there should be a three-character abbreviation used to uniquely identify each module. The name of every function and globally-accessible value declared within the module should begin with that three character abbreviation followed by the underscore.