CodingStandards

From PSwiki
Jump to navigation Jump to search

Automatic Code Formatter tool

To be compliant with the guidelines below a good start is to use:

http://astyle.sourceforge.net/

with the following options: --style=allman --align-reference=name --align-pointer=type --indent-switches --unpad-paren

To use it in msvc2010 use this short guide.

Indentation/Tabs/Space Policy

  • Indent using 4 spaces for each level.
  • Do not use tabs, use spaces. Most editors can substitute spaces for tabs.
  • Tabs should be fixed at 8 spaces. Don't set tabs to a different spacing, uses spaces instead.
  • Indent as much as needed, but no more. There are no arbitrary rules as to the maximum indenting level. If the indenting level is more than 4 or 5 levels you may think about factoring out code.

Justification

  • Tabs aren't used because 8 space indentation severely limits the number of indentation levels one can have. The argument that if this is a problem you have too many indentation levels has some force, but real code can often be three or more levels deep. Changing a tab to be less than 8 spaces is a problem because that setting is usually local. When someone prints the source tabs will be 8 characters and the code will look horrible. Same for people using other editors. Which is why we use spaces...
  • When people using different tab settings the code is impossible to read or print, which is why spaces are preferable to tabs.
  • Nobody can ever agree on the correct number of spaces, just be consistent. In general people have found 3 or 4 spaces per indentation level workable.
  • As much as people would like to limit the maximum indentation levels it never seems to work in general. We'll trust that programmers will choose wisely how deep to nest code

Be Const Correct

C++ provides the const key word to allow passing as parameters objects that cannot change to indicate when a method doesn't modify its object. Using const in all the right places is called "const correctness."

It's hard at first, but using const really tightens up your coding style. Const correctness grows on you.

If you don't use const correctness from the start it can be nightmare to add it in later because it causes a chain reaction of needing const everywhere. It's better to start being const correct from the start or you probably won't be.

You can always cast aways constness when necessary, but it's better not to.

For more information see http://www.possibility.com/Cpp/const.html

Braces {} Policy

Place brace under and inline with keywords:

while(condition)
{
    ...
}
if(condition)
{
    ...
}
if(condition)
{
    ...
}
else
{
    ...
}

Parentheses () Policy

  • Don't put a space after reserved words like if [eg: if() not if ()]
  • Don't put a space after function names [eg: Greet() not Greet ()]
  • Don't put internal spaces [eg: if(hello) not if( hello ) ]

One Statement Per Line

There should be only one statement per line unless the statements are very closely related. Separate logical coding units such as methods, conditional expressions or variable declaration blocks with blank lines.

The reasons are:

  • The code is easier to read. Use some white space too.

One Variable Per Line

Related to this is always define one variable per line:

Not:

 char** a, *x;

Do:

 char** a = 0;  ///< add doc
 char*  x = 0;  ///< add doc

The reasons are:

  1. Documentation can be added for the variable on the line.
  2. It's clear that the variables are initialized.
  3. Declarations are clear which reduces the probability of declaring a variable when you actually mean to declare a pointer.

Enum Names

Labels All Upper Case with '_' Word Separators This is the standard rule for enum labels. Example

  enum Button_StateType
  {
      BUTTON_OFF,
      BUTTON_ON
  };

#define and Macro Names

Put #defines and macros in all upper using '_' separators.

Justification

This makes it very clear that the value is not alterable and in the case of macros, makes it clear that you are using a construct that requires care.

Some subtle errors can occur when macro names and enum labels use the same name. Example

 #define MAX(a,b) blah
 #define IS_ERR(err) blah

Class and Method names

  • use a capital first letter, then lower case except when starting a new word (eg: HelloWorld)

Variable Names

  • Start with lower case and then all the follow up words should have an upper case first letter (eg: camelCase)
  • Use descriptive names (eg: no X Y Z W but for example practicalExperience. x y z is descritive for cordinates)

Variable Definition

Use these styles:

  • char* name;
  • char &name;
  • char* &name;

#includes

  • In header files try and use prototype declarations instead of #including the header.

Justification

  • Doing this keeps the header files clean and uncomplicated. It reduces warning spillage into unrelated source files.

Header Template

This is a basic template to use for header files. Note that in class the order of information is public then protected then private. This is because in the majority of cases when somebody is looking at the class they want to know the interface of it and not the private data members of it.

 /*
 * fileName.cpp              creator <email@email.address>
 *
 * Copyright (C) 2001-2008 Atomic Blue (info@planeshift.it, http://www.atomicblue.org) 
 *
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation (version 2 of the License)
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 *
 */
 #ifndef XXX_HEADER
 #define XXX_HEADER
 //====================================================================================
 // Crystal Space Includes
 //====================================================================================
 ...
 //====================================================================================
 // Project Includes
 //====================================================================================
 ...
 //====================================================================================
 // Local Includes
 //====================================================================================
 ...
 //------------------------------------------------------------------------------------
 // Forward Declarations
 //------------------------------------------------------------------------------------
 ...
 /** Short Description of class.
  * Detailed Description of class
  */
  class XXX
  {
  public:
  protected:
  private:
  };    
  #endif

Documentation

Jave documentation style is used. doxcygen with the JAVADOC_AUTOBRIEF will generate correct reports.

 /** This is a brief description that ends with a dot. Detail
  *  description follows.
  */
 int var; ///< Description of variable.