Coding Guide Lines

You are here: Home > Developer Documentation > Coding Guide Lines

Help improving these guide lines!

• Add file name conventions (camelCase, no _, small/big, ...)
• Add something template meta programming specifig: public typedefs like ValueType and type (boost resultOf)
  • ValueType is a public typedef for internal storage types (e.g. a single element of a field)
  • type traits should either define a ::result or ::type (the literature is not very unified in that)
  • what is necessary for a resultOf (Rene?)
  • other common type defs in PIConGPU: borders/margins
• doxygen: \cmd or @cmd style? /** ... */ style (not // or /*!)

General C++ Style Guide

1. Spaces and Indentation

• use spaces around assignment operators, e.g., a = b / c;
• no TABS, use 4 spaces per level
  • a new namespace does not get spaces in front since we sometimes nest them 4 to 5 times:

namespace Clair
{
namespace Bob   /* no spaces */
{
namespace Alice /* no spaces */
{
    /* this guy gets intended */
    Struct FooMe;

} // namespace Alice
} // namespace Bob
} // namespace Clair

2. Pre-Compiler

• Macros are written ALL_UPPERCASE and can use _
• Align nested pre-compiler commands

#if(VARIABLE_BOB==1)
#    if(VARIABLE_ALICE==1)
#        define HPC +1
#    endif
#endif

• Macros with newlines: align \ symbol to column 80
• Describe how PreProcessor Macros are unrolled (excellent example)

/*      < typename T0, ... , typename TN    > */
template<BOOST_PP_ENUM_PARAMS(N, typename T)>
/*                      ( const T0, ... , const TN        ) */
HDINLINE void operator()( BOOST_PP_ENUM_PARAMS(N, const T)) const

3. Types and Object Naming Conventions

• TypeNames and objectInstances, e.g. definition of EventTask myEventObject;
• use CamelCaseNames instead of in-name _ if not explicitly stated otherwise (e.g. fixed pre-/suffixes)
• References and Pointers are part of the Type (no space), e.g. foo( int* i, float& b )

4. Functions, Functors, Members, ...

• omit curly braces for one-liners

if( a == b )
     myFunction( c );

somethingElse();

• braces on new lines (Yeah, East Coast Style!)

if( a == b )
{
     /* do something */
}

• ( ... ) are part of the caller (see above), no space to that caller but spaces to arguments inside
• same for template arguments: template< ... >
• object members are pre-fixed with an m_ (allows to fulfil -Wshadow in constructors, see below)

class A
{
  private:
    int m_myInt;

  public:
    A( int myInt ) : m_myInt( myInt )
    {
        /* ... */
    }
};

• Template Arguments shall be prefixed with T_ followed by upper case letter camel case for types (class, struct and native C types):

template<typename T_ValueType, class T_SomeOption>
class XYZ;

• Template Arguments shall be prefixed with T_ followed by lower case letter camel case for values:

template<size_t T_size, bool T_isValid>
class XYZ;

• function types and members can become quite long, use newlines:

template<class T_A>  /* templates */
HDINLINE void        /* compiler hints [optional newline] return type */
functionName( ... )  /* name params */
{
    /* ... */
}

or in a real-world example

/** brief description
 *
 * long description
 *
 * \tparam T_A is our first template parameter
 * \param a is our first parameter
 * \param b is our second parameter
 */
template<class T_A>
HDINLINE void
functionName( int a,
              double b )
{
    /* ... */
}

5. Comments

• Copyright notice:
  • each file must contain the corresponding (L)GPL header, Author(s) + current year (if changed - and a commit of a file means a change)
  • you never remove an author or a year, you only add to them
  • the following tool will add the header for you
• prefer explicit /* ... */ style
• use Doxygen syntax for function/class description, choose the style /** \doxygenVariable ... */
• you should avoid inline comments at all but you must not use ...; // comment as an inline comment
• close namespaces with a comment: } // namespace itsName

Git: Naming Conventions for Branches

this section will be moved somewhere else!

• master -> tags: alpha, beta, 1.0
• dev -> release-... -> master (tagged commit)
• topic-myNewFeature
• fix-aHotfixName

Auto-Testing via ?

• vera++ (supports transformations -> auto-create pull request to pull request branch with proposed changes?)
• uncrustify
• cppcheck