Coding style and standards

From user's Wiki!
Jump to: navigation, search

Good coding standards are important in any development project, but particularly when multiple developers are working on the same project. Having coding standards helps ensure that the code is of high quality, has fewer bugs, and is easily maintained.

First rule, if in doubt, ask.

Coding Standards

Goals:

  • Readable. As much as possible, the coding style should help the reader to understand the code.
  • Easy to compare. When using a diff-tool such as WinMerge, it should be easy to see the changes between two versions of a source file.
  • Easy to browse. It should be possible to quickly find the code you are looking for, without needing to do a lot of eye-balling of the screen or pressing Page Up / Page Down too often (i.e. prevent pressing Page Down to see a part of code that could fit on the current screen as well).
  • Conform to existing standards. Our choice of style should not be so different from existing standards that we confuse users of our code. In general, we should try to meet all the above criteria. Then, in cases where 2 choice are equally attractive, we will choose the one that is more conforming to existing standards, like itk.

Spelling

Spelling of class, function, variable and constant names should generally be in accordance with British English rules (en_GB).

Indenting and Line Length

Use tabs to indent, not spaces. Make sure that the tab-stops are set to only 4 spaces in length.

The line length should not exceed 75 characters. Much wider than this linewraps badly with diff; much shorter than this makes code look too sparse. Using WinMerge, it's possible to inspect changes between versions without scrolling to the right if lines do not exceed screen width. With the 'Display indicator after column' feature of Visual Assist, we can check that we do not exceed the limit. A line of code must not exceed 80 characters.

Control Structures

for( unsigned int i = 0; i < 3; ++i )
{
   // do stuff...
}

if( condition )
{
   // do stuff...
}
else if( other condition )
{
   // do stuff...
}
else
{
   // do stuff...
}

Comments

Each file must contain a copyright comment:

/*
* Copyright (c) 2009,
* Computational Image and Simulation Technologies in Biomedicine (CISTIB),
* Universitat Pompeu Fabra (UPF), Barcelona, Spain. All rights reserved.
* See license.txt file for details.
*/


Inline documentation for classes should follow the DoxyGen rules (JavaDoc style). More information about DoxyGen can be found here: Documenting the code

/**
* Class brief description.
* Class long description.
* \ingroup group gmWidgets
* \author author Chiara Ricobenne
* \date date 21 July 2010
*/
class MyClass
{
public:
   /**
   * Method brief description.
   * Method long description (if not obvious).
   * \param[in] input1 My first input.
   * \param[in] input2 My second input.
   * \return The result of my method.
   */
   bool MyMethod( const class& input1, const class& input2 );

   //! Get \a myFlag.
   bool GetMyFlag() const;

private:
   //! My internal variable
   bool m_myFlag;
}

Always include and keep up to date in these information, whenever a new class is generated/modified

Include a comment for each public method/member of a class. The comment should contain all relevant information (meaning of members, default values, meaning of input parameters, results values, exceptions thrown if any, basic meaning of the method, calling order.

Functions definitions

All operation definitions should reside in source files. The header files should declare an interface, the source file should implement it. When looking for an implementation, the programmer should always know that it is found in the source file.

Header file:

class MyClass
{
public:
   int GetValue() const;
private:
   int m_value;
}

Implemetation file:

int MyClass::GetValue() const
{
   return m_value;
}

Try to avoid all in one file:

class MyClass
{
public:
    int GetValue() const {return m_value;} // Avoid...
}


Naming conventions

Files

Files start with lower-case and follow camel case style. The prefix should be a common one to your library. Header files are named '.h', while implementation files are named either '.cpp' or '.txx', depending on whether they are implementations of templated classes. An example could be: blLightObject.h and blLightObject.cpp.

Class/Methods/Functions

Class names, Methods and Functions start with upper-case and follow camel case style.

class DicomReader
bool GetMyVariable()

Class data members

Class data members names start with the 'm_' prefix followed with lower case name and follow camel case style. The use of the prefix makes it optional to use the this pointer to access members since it is clear that it is a member variable.

double m_precision;

Variables that are pointers do not need any prefix or postfix for that (make sure that when you allocate a buffer, you assign it to a smart pointer or use a Janitor to free the memory later). Don't use a prefix for variables such as int nNrOfImages or double dPrecision, except when it is needed to distinguish between different variables such as nNrOfImages and dNrOfImages. In most cases, the user already expects 'nrOfImages' to be an integer and 'precision' to be a double. Even if precision happens to be a float, this does not cause any problems with understanding the code.

Local variables

Local variables names start with lower-case and should not be more than one word. If they are, they follow camel case style.

float tolerance;

GUI specific

In GUI code, use a prefix for controls that identify the type (e.g. lblSeed, btnSetSeed, leSeed). General rules:

  • No more than 3 letters
  • If it has one word, remove vocals and use consonants
  • If has more than one word, take first letter from each word

Use the following conventions:

  • Names ending in UI indicate that the class (or file) only contains visual elements and functionality related to visual appearance (when you fill in a textbox, a button become visible). In other words, they indicate an UI class.
  • Names ending in Widget indicate that the class (or file) extends the UI class with functionality.
  • Names ending in WidgetPlugin indicate a file that is used to register the widget in QtDesigner (so that you can drag-and-drop into other widgets).

Note on prefixes convention Almost every element should have an unambiguous prefix that identifies the element type, especially if later you will need to refer to them in the child class. Most typical cases are the following:

  • gb -> group box
  • cmb -> combo box
  • chb -> check button
  • ly -> layout
  • lb -> label
  • le -> line editor
  • rb -> radio button

Solve conflicts like combo box (cb) and check button (cb) adding second consonant from first word (cmb) and (chb) respectively. Note on the widget naming convention: Use clear names, like Maximum, Minimum, or even BinaryThresholdMaximum.