Coding Style

All files should start with the following text. If modifying an existing file you should leave the copyright notice. For a completely new file, you should add the appropriate copyright notice.

/*=========================================================================
Authors: The GoFigure Dev. Team.
at Megason Lab, Systems biology, Harvard Medical school, 2009-11

Copyright (c) 2009-11, President and Fellows of Harvard College.
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
Neither the name of the President and Fellows of Harvard College
nor the names of its contributors may be used to endorse or promote
products derived from this software without specific prior written
permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS
BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

=========================================================================*/

Naming Convention

Naming Classes

Naming Files

  • Files should have the same name as the class. Header files are named .h, while implementation files are named either .cxx or .txx, depending on whether they are implementations of templated classes.
  • It is important to note that VTK, ITK, and Qt classes fall under their respective namespaces.
  • Qt classes involved in the GUI should start with QGo.

Naming Functions and Methods

General case

Qt based classes

Naming Class Data Members

General case

Class data members are prepended with m_ as in m_Size. This clearly indicates the origin of data members, and differentiates them from all other variables.

Qt based classes

Naming Local Variables

Local variables begin in lowercase. There is more flexibility in the naming of local variables; please remember that others will study, maintain, fix, and extend your code. Any bread crumbs that you can drop in the way of explanatory variable names and comments will go a long way towards helping other developers.

Naming Template Parameters

Template parameters follow the usual rules with naming except that they should start with either the capital letter T or V. Type parameters begin with the letter T while value template parameters begin with the letter V.

Naming Typedefs

Typedefs are absolutely essential in generic programming. They significantly improve the readability of code, and facilitate the declaration of complex syntactic combinations. Unfortunately, creation of typedefs is tantamount to creating another programming language. Hence typedefs must be used in a consistent fashion.

The general rule for typedef names is that they end in the word Type. For example

 typedef TPixel PixelType;

However, there are many exceptions to this rule when dealing with concepts that are expressed partially in the names used to implement the concept. An iterator is a concept, as is a container or pointer. These concepts are used in preference to Type at the end of a typedef as appropriate. For example

 typedef typename ImageTraits::PixelContainer PixelContainer;

Here Container is a concept used in place of Type.

Code Layout and Indentation

The following are the accepted code layout rules and indentation style. After reading this section, you may wish to visit many of the source files found in ITK. This will help crystallize the rules described here.

General Layout

Each line of code should take no more than 80 characters. Break the code across multiple lines as necessary. Use lots of whitespace to separate logical blocks of code, intermixed with comments. To a large extent the structure of code directly expresses its implementation.

The appropriate indentation level is 2 SPACES for each level of indentation. DO NOT USE TABS!!'''. Set up your editor to insert spaces. Using tabs may look good in your editor but will wreak havoc in someone else's.

The declaration of variables within classes, methods, and functions should be one declaration per line.

 int    i;
int j;
char * stringname;

Spaces (USE THEM!)

GoFigure2, like ITK, makes liberal use of spaces to improve the readability of code. When in doubt, use a space. Common examples:

  • Separate expressions from their enclosing parent:
    if( a < b )
    {
    a = ( 1 + 1 ) / 2;
    }
  • Separate arguments from their enclosing param and from other args (there should be a space after every comma):
    foo( int a )
    {
    foofoo( a );
    foofoofoo( a, b );
    }
  • Favor right-flush for lines that are continuations of previous lines:
     this->IsMyReallyLong()->ITK()
    ->FunctionCall()
  • Use ( void ) when declaring a function that takes no arguments:
     int DoesNothing( void )
    {
    }
  • Use spaces before and after raw pointer declarations:
     int * a;
  • You do not need to use spaces when accessing raw pointers:
     a->b;
    *a = b;

Break complex methods into multiple lines - program in a way that makes it easy for your code to be debugged by others. Examples:

  • avoid ?: statements should not be used instead of if...then statements
  • Limit the variety of operators that appear in any one line of code

Class Layout

Classes are defined using the following guidelines.

  • Begin with #include guards.
  • Follow with the necessary includes. Include only what is necessary to avoid dependency problems.
  • Place the class in the correct namespace.
  • Public methods come first.
  • Protected methods follow.
  • Private members come last.
  • Public data members are forbidden.

The class layout looks something like this:

 #ifndef __ClassName_h
#define __ClassName_h

#include "itkImageBase.h"
#include "itkPixelTraits.h"
#include "itkDefaultImageTraits.h"
#include "itkDefaultDataAccessor.h"

namespace itk // if required
{
template < class TPixel, unsigned int VImageDimension=2,
class TImageTraits=DefaultImageTraits< TPixel, VImageDimension > >
class Image : public itk::ImageBase< VImageDimension >
{
public:
....stuff...
protected:
....stuff...
private:
....stuff...
};

}//end of namespace

#endif
//end include guard

Method Definition

Methods are defined across multiple lines. This is to accommodate the extremely long definitions possible when using templates. The starting and ending brace should be indented. For example:

 template< class TPixel, unsigned int VImageDimension, 
class TImageTraits >
const double *
Image< TPixel, VImageDimension, TImageTraits >
::GetSpacing( ) const
{
...
}

The first line is the template declaration. The second line is the method return type. The third line is the class qualifier. And the fourth line in the example above is the name of the method.

Use of Braces { }

Braces must be used to delimit the scope of an if, for, while, switch, or other control structure. Braces are placed on a line by themselves:

  int i;
for( i=0; i<3; i++ )
{
...
}

or when using an if:

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

KWStyle

  • Download and compile KWStyle.
  • You don't need to install it.
  • in your gofigure2 build directory, start ccmake.
  • modify variable use KWStyle to ON,
  • specify the path to KWStyle Build directory
  • verify the style of your code with the command :
    ctest -R Style -VV >> style.log