Currently viewing: GipsySoft » Front Page» Articles

Coding Conventions and Guidelines

Overview

This is a basic list of guidelines for us to develop consistent source code and robust products. It is a set of guidelines rather than a list of orders or commandments. Some projects have their own coding conventions and guidelines, which are in addition to these.

This is a live document, additions, corrections and suggestions are all welcome.

Developer Goals

Developer goals, in order of importance.

Correct
Make the code right. Itís no good having lots of code that is so buggy as to be useless, or in fact to solve a different problem.
Maintainable
Make the code maintainable. Using clever code, cool or interesting compiler tricks may impress a junior developer but when one of your peers needs to make sense of your code it is anything but clever.
Fast/Small
Make the code as small and optimal as possible, remember that big and slow are bugs.
Reusable
Think of other places in the project, or other projects, where your code may be used.
Portable
Ensure the code is as portable as possible, use standard C functions where possible.

General

  • Use the maximum warning level your compiler has.
  • If possible set compiler warnings as errors, this ensures accidental warnings need to be fixed.
  • Have a daily build process that builds the entire system and if possible have some automated regression tests.
  • Use automatic testing tools such as Numega's Boundchecker or Gimpel Software's PC/LINT.
  • Don't guess where your code is slow, use a profiler. Either use the one that comes with your compiler or try Numega's TrueTime.
  • Read books such as those listed on my book list
  • Use string resources for all user messages, this makes translation to other languages much easier.

Source Files

  • Use mixed case long filenames for source files.
  • Where a single function has a source files use the function name as the file name.
  • Only include header files that are needed.
  • Place all declarations, constants and other definitions in their own section after any #includes.
  • Only have one class or function per source file where possible.
  • All source files should have the standard header and copyright notice. Each source file should have a description of itís contents in the standard header. Standard header also includes your email address. There are standard VC macros to make this easier.
/*-----------------------------------------------------------
Copyright (c) 1998,1999 Gipsysoft. All Rights Reserved.
File:		<Filename goes here>
Owner:	<Your email goes here>
Purpose:	<File description goes here>
-----------------------------------------------------------*/

Header Files

  • All header files should have the standard banner.
  • They should have an include guard in the following format:
		#ifndef EDITSECTION_H
		#define EDITSECTION_H
		//	Code
		#endif	//	EDITSECTION_H
  • Header files within header files should have the include guard around the included header file.

Layout

  • Use space. The compiler doesnít mind if there is a lot of space between lines. Blank lines actually make the code look better. Do not try to compress several simple lines of code into one, unreadable line of code.
  • Use spaces inside parenthesis e.g. if( expression ) instead of if (expression)
  • Do not use spaces inside empty parenthesis e.g. foo() instead of foo( )
  • Place braces for if statements below the if keyword. Same for while:
    	while( exp )
    	{
    	}
    
    	if( exp )
    	{
    		//	...
    	}
    	else
    	{
    		//	...
    	}
    
  • Use blank lines to separate logical blocks of code within a function.
  • Look at sample code to find out if you are unsure of a particular layout (use Find-in-Files)

Variables

  • Use simple Hungarian notation. Most of our naming comes directly from MFC and general Windows code. If you are unsure look at sample code or ask.
  • Prefix class names with "C" e.g. CMyObject
  • An abstract base class should have it's name postfixed with ABC e.g. CMyObjectABC

Comments

  • Every source file must start with the standard Gipsysoft copyright notice and comment lines.
  • Comment each function describing what and how the function works.
  • Use a review comment where you are unsure of something e.g.
		//REVIEW russf Not sure if the following is portable.
  • Use C++ style comments rather than C style comments where appropriate.
  • Document all assertions with a single line comment, give a reason why the assert could fail and a simple remedy.
  • Comment reasons why code has been commented out rather than just deleted.
  • Try to comment more than you think is necessary, too much is better than none.
  • When you move/delete code ensure the comments are moved/deleted too.

Classes

  • Classes should have the following layout.
	Class CMyClass {
	Public:
		// Constructors
		// Destructor
		// Methods
		// Variables (if you must have public member variables)
	Protected:
		// Methods
		// Variables
	Private:
		// Methods
		// Variables
	};
  • Do not use public variables unless where necessary. Document why the variables are public.
  • Use the constructor initialisation list where appropriate.
  • Use explicit for all single parameter constructors where implied conversions are not required/allowed.
  • Use const for all appropriate members variables, functions and function parameters.
  • Only use mutable where necessary.
  • Do not use operator overloading unless it has a significant positive impact on both readability and maintainability.

Debugging

  • Assert everything. Add a comment about why the ASSERT can fail and list possible remedies.
  • Ensure your assertions are correct. Bogus assertions can be time consuming.
  • Add TRACE messages when something really bad happens but where there may not be a handler for it. e.g. output a TRACE message before an exception is fired.
  • Debug the data. Many hard to find problems are not problems with teh code at all but are problems with the data. Check all data is correct, this includes simple variables and objects.