Style Guide

Motivation

Some of the reasons for using a style guide are:

• It can be jarring to see different code styles within one project;
• It will make it easier for your instructor to read your code if it is written in a familiar style;
• It might make it easier to read the code of your fellow team members;
• Style guides are widely used in industry and even in open source projects, so it will be good practice for you to get used to using them.

Overview

The explicit rules listed on this page are designed to help you avoid some obvious code style violations. You should also look at the existing code and make your code as consistent as possible.

Style guide complicance is, however, not nearly as important as high quality code. If your code uses high quality coding standards, your instructor will be much more lenient on any small differences in code style.

Explicit Rules

Indentation

Indent to show structure. Use 3 spaces to indent. Do not use tab characters.

Where possible, configure editors to insert spaces instead of tab characters - the tab character is interpreted differently by different programs and its use in the formatting of code should be avoided.

Naming conventions

• Never use names that begin with an underscore or contain a double underscore.
• Only use upper case for macros LIKE_THIS and don't use common words or abbreviations.
• Classes and enums should be named LikeThis.
• Methods, functions and variables (including private member variables) should be names likeThis.
• C implementation files should be given the extension .c. C++ implementation files should be given the extension .cpp. A C++ source file should be named after the principal class it contains. Example: The C++ class SomeClass would have header file SomeClass.h and body file SomeClass.cxx.

Brace placement

void useBracesLikeThis(int x)
{
   // Always add braces, even if it's only a single statement.
   if (x < 3)
   {
      cerr << "well done" << endl;
   }
}

Use C++ instead of C

Be a C++ programmer as much as possible, for example:

• Don't use #define when you could use const;
• Don't use C-style casts, use the appropriate C++ casting operators.
• Narrow the scope of variables as much as possible and declare them as late as possible. For example, prefer C++ style for loops:

  // Even better, use iterators
  for (int i = 0; i < v.size(); i++)
  {
     // do stuff
  }
  

Miscellaneous

• Use POSIX defined libc routines whenever possible. If you are doing something machine dependent us the appropriate predefined manifest constant - like _MSC_VER for interfacing to the Win32 API.
• Use POSIX and ANSI standard manifest constants whenever possible for things like the largest machine value, e.g. HUGE_VAL.
• Use forward declarations wherever possible to avoid includes in header files.
• If a local variable isn't going to change it's initial value make it const.
• Use any length of line you like, but don't be excessive.
• Write useful comments, don't just repeat the code.

Last edited Mon Jun 4 21:14:14 2007 by John Funge.