Coding standards reference

The following document describes the best practices for the syntax and style of writing code in an imperitive language (such as Java or C/C++). As with most rules, they should be followed almost all of the time. The following standards will define an aspect of the quality of the code submitted and will be graded accordingly.

There are cases where violating these standards is preferential or necessary. In these cases there should be a comment added in the code explicitly stating what standard is being violated and a reasonable explanation why. Reasons like "I ran out of time to do it correctly" will not be accepted.

Code standards:

  • The maximum width of a line, including whitespace and the final return character, is 80 characters.

  • One or two blank lines should be used to visually seperate logically distinct code segments.

  • The preferred style of bracket alignment for different control structures is illustrated below: 
    if (...) 
{
    ...
} 
else 
{
    ...
}
    to allow for quick matching of brackets.

  • The preferred style of bracket alignment for function definitions is illustrated below: 
    void myfunction(int someParam)
{
    ...
}

  • All user-defined functions must have a prototype declared above the main routine and the full function implementation given below the end of the main routine.

  • All indentation is to consist of levels of 3-5 spaces, and spaces must be used instead of tabs.

    There should be one layer of indentation for each and every level of nesting associated with an instruction, e.g. 

            int main()
        {
        
            ...
            if (x < y) 
            {
               ...
            } 
            else 
            {
               ...
            }
            ...
        }
    Layers of nesting include functions (including the main routine), loops, if/else statements, switch statements, and multiline comments.

  • Comments should generally be used to explain either the intended behaviour of a code segment or the logic behind a code segment - comments should not simply echo code behaviour.

    As an example, the logic of the following might not be immediately obvious: 

       char dig;
   cin.get(dig);
   int  val;
   val = dig - '0';
    The workings make more sense with some explanatory comments: 
       // Get the user to type a single digit, then store it as an int
   char dig;
   cin.get(dig); // read the digit entered

   // subtract the ascii value of digit '0' to get the integer equiv
   int val = dig - '0';

  • All variables must be declared locally (i.e. inside the main routine or some other function) as close to the first use of the variable (if possible) within a the scope of the routine, procuedure or function, and must have meaningful/explanatory names.

    Variables should be initialized and accompanied by a short comment explaining their purpose. (When not unambiguously obvious what its purpose is).

    Full hungarian notation is not necessary, but object member variables should pe preceded with "m_" to identify its scope as a member of an object definition.

  • There should be no hard-coded numeric values in your programs other than 0 and 1 - any such values should be replaced by constants (either global or local).

    Constants should be given a meaningful/explanatory name.

  • For clarity, all arithmetic expressions should be fully parenthesized.

    Complex arithmetic expressions should either be broken into smaller, clearer steps or accompanied by suitable explanatory comments.

  • Constant/variable comparisons should have the constant on the left-hand side of comparison operator (to avoid accidental assignment).
    eg. 
    	const int ONEVALUE = 0;

	// Will compile without error but is likely wrong, meant to be: if( var == ONEVALUE )
	if( var = ONEVALUE ) 

	// Logically equivalent but will cause error when: if( ONEVALUE = var )
	if( ONEVALUE == var )

  • Const correctness. Classes should define its members to allow for mutable and immutable use by the user. Wikipedia description


    • For C++ coding any practices described as beneficial within Scott Meyers' "Effective C++", or "More Effective C++" books will be considered as acceptable practices for the purposes of coding standards.