Technical Documentation: Developer's Guide

From Go4IT project

Contents 1 Foreword 2 Source Code Formatting 2.1 Naming conventions 2.2 File extensions 2.3 File names 2.4 General Rules 3 Design Issues 4 Documentation

Foreword

This document shortly describes guidelines for C++ developments in Package 2. They shall not be regarded as strict rules, but as proposal for harmonising the developments between the different partners. It is not required to refactor developments that have been done so far. Their aim is to improve the readability, accessibility, reliability and ultimately the reusability of the developments. They are grouped in three sections : source code formatting, design issues and documentation.

Source Code Formatting

Naming conventions

class XxxxxXxxx

• attribute mXxxxxXxxx
• static attribute msXxxxxXxxx
• member function XxxxXxxxx()
• member typedef mXxxxXxxx_t
• member enum AxxxBxxx

enum value abXxxxxx

local variable xxxxx_xxxxx

static variable sXxxxxXxxx

global variable gXxxxXxxx

function xxxx_xxxx()

typedef xxxx_xxxx_t

macro, constant XXXX_XXXX

File extensions

C++ files .cpp

C files .c

Headers .h

File names

Header ClassName.h

Inline functions ClassNameInl.h

Implementation ClassName.cpp

General Rules

Use explicit method names (eg. DumpDataToFile() instead of DataFile())

Try to keep a similar design between different classes. Especially keep the name of member functions consistent.

Use namespaces

go4it::system_adapter

go4it::codec

...

Do not put a `using namespace' directive at global scope in a header file.

Enclose headers inside a #ifndef directive

  #ifndef namespace_filename_h
  #define namespace_filename_h
  #endif

Indent the code. eg:

for (i=0 ; i<a ; i++)
{
   if (i == a)	{
      ...
   }
}

Use brackets inside if, for, while... statements:

if (a == b)	{
   do_something();
}

is preferred to:

if (a == b)
   do_something();

Insert spaces and blank lines to improve readability:

if ((aaa (b, c) + d) == e) {
   ...
}

is preferred to

if((aaa(b,c)+d)==e) {
   ...
}

Design Issues

For every function check the validity of parameters with assert(). This prevents cases of undefined behaviour and eases bug detections.

Avoid defining public attributes.

Compile with a high level of warning, and resolve each warning.

Avoid C-style casts, prefer c++ casting operators. Use static_cast<> and reinterpret_cast<> only if you are 100% sure of what you are doing. Otherwise use dynamic_cast<>.

Avoid overloading operators other than, except:

• &ostream operator<<(ostream&, ... )
• &istream operator>>(istream&, ... )
• when their meaning and usage is obvious, when they cannot be misinterpreted by a reader who is not familiar with the code. Also keep consistency between operators, eg:

`a = a + b' should be equivalent to `a += b'

`a->b()' should be equivalent to `(*a).b()'

Avoid multiple inheritance, except for very special cases where it is safe and useful (like defining an interface).

Use const correctly and at every place it is suitable.

Prefer using references instead of pointers for function parameters and return value, except in special cases like:

• handling C data (eg. char* for a null terminated string)
• transfer of ownership of an object

More generally when a pointer is needed, try the first solution that fits:

1. use a reference
2. use a smart pointer (simplifies memory management)

http://www.boost.org/libs/smart_ptr/smart_ptr.htm

1. use a pointer

Documentation

Document classes and functions in header files with javadoc-style tags, so than they can be processed with doxygen or any other extraction tool.

Use comments inside functions when the code is not obvious at first glance :

• step by step description
• meaning of local variables

Document decisions: when you have an important choice to do in the implementation, let a short statement telling which choice was made and why.

Mark problems in the code and prepend them with the keyword FIXME or TODO.

Provide README files in the source tree describing:

• how files are organised
• installation instructions
• status of the work