Lecture notes for the Introduction to Computer Science I by James Tam Return to the course web page

Coding Standards

Note: This link was created as a brief reference.  For additional details you should look at your course notes because I have provided important style considerations throughout the lectures.

 

Documentation

 
  • Each module should be documented separately (including the 'main' module)
   
  • What does the module do
   
  • Who is the author
   
  • When was it last modified
   
  • What assumptions (pre-conditions) are made for the module to run correctly e.g., what are the valid data ranges for the parameters
   
  • Are there any special algorithms that are used and should be credited e.g., 'This procedure implements the Shell sorting algorithm as created by Donald Shell.'

Variable declarations and using variables

 
  • Variables should have meaningful names (see the 'programming intro' notes for additional details).
  • Variables should be initialized to a default starting value prior to being used (e.g., such as when it becomes part of a loop or decision making construct).
  • Global variables should be avoided

Constant declarations

 
  • Constants should follow the same naming conventions as variables but the should be should all be upper case (see the 'programming intro' notes for additional details)

Layout and formatting

 
  • Each statement should be on a separate line.
  • Statements that are the 'body' of a construct e.g., decision making construct, loop or program module should be indented in a consistent manner.  Corresponding 'begin' and 'end' statements should be aligned on the same left axis.

Redundant code

 
  • If the same code is used repeatedly throughout the program then consider implementing the code once in a function or procedure and reusing this code.  E.g., the code to display the contents of a 1D array is a common operation and will likely be used throughout a program that implements common list management functions.  Rather than repeating the same code throughout the program, it should instead be implemented as a module and then the module can be called as necessary.

Error checking

 
  • Examples of some of the common error cases to check are illustrated throughout the first section of the notes but a brief summary includes:
   
  • Input testing: Checking that the program reads the input that is desired by the programmer (see the 'programming intro' notes for additional details).
   
  • Testing decision making constructs: The three most common test conditions include obvious true cases, obvious false cases and boundary cases see the 'decision making' notes for additional details).
   
  • Testing loops: The three most common test conditions includes when the loop never runs, when the loop runs exactly once and when the loop runs 'n' times (some arbitrary positive integer that is greater than one).  (See the notes on loops for additional details).