Feel++ Coding Styles

This is an overview of the coding conventions we use when writing Feel++ code.

1. Clang Format

clang-format is a powerful tool to reformat your code according to rules defined in a .clang-format file at the toplevel directory of your software.

Feel++ has such a file and define the indentation, space and breaks rules defined later on.

For clang-format to function properly, follow the Comments rules.

To apply Feel++ rules on a file a.cpp in a Feel++ sub-directory, type

clang-format a.cpp

to dump the results of the reformating to the standard output or type

clang-format -i a.cpp

which will replace a.cpp by the reformated file.

be careful when reformating, make sure nobody is working on that file, to avoid creating possibly massive conflicts with the persons currently modifying the same code when they get merged.

2. Header files and multiple inclusions

To avoid multiple inclusions, wrap every header files using the following technique

// say we have myheader.hpp
#if !defined(FEELPP_MYHEADER_HPP)
#define FEELPP_MYHEADER_HPP 1

// your header here...

#endif // FEELPP_MYHEADER_HPP

more details here

3. Naming Convention

In Feel++, we basically follow the same naming conventions as in Qt and KDE.

Class names starts with a capital. The rest is in camel case. Function names starts with a lower case, but the first letter of each successive word is capitalized.

Functions and classes should be in the Feel namespace.

The prefix set is used for setters, but the prefix get is not used for accessors. Accessors are simply named with the name of the property they access. The exception is for accessors of a boolean which may start with the prefix is.

Acronyms are lowercased too. Example: Url instead of URL and isFemEnabled() instead of isFEMEnabled()

Accessors should usually be const.

This example shows some possible functions names

class A
{
public:
    void setMatrix(const Matrix& c);
    Matrix matrix() const;
    void setDiagonal(bool b);
    bool isDiagonal() const;
};

4. Reserved identifiers

5. Indentation

  • 4 spaces are used for indentation but not in namespace

  • Spaces, not tabs!

  • Suggestion: use emacs and [emacswiki.org/emacs/dirvars.el dirvars.el], here is the content of .emacs-dirvars in top Feel++ directory

    indent-tabs-mode: nil
tab-width: 4
c-basic-offset: 4
evaluate: (c-set-offset 'innamespace '0)
show-trailing-whitespace: t
indicate-empty-lines: t
evaluate: (add-hook 'write-file-hooks 'delete-trailing-whitespace)
namespace Feel
{
// no space indentation in namespace
Class A
{
    // 4 spaces indentation
    A() {};
    void f();
};
}

6. Comments

Use C++ style comment // rather than /* */. It uses less characters but also it is easier to reflow using clang format.

/* Wrong
  the doc
  */

// Correct
// the doc

6.1. Doxygen

Doxygen is the tool to document Feel++ and create a reference manual

Use //! to comment function, variables, classes rather than /** */, it allows to reflow comments using clang format.

//!
//! @brief the class
//! @author me <me@email>
//!
class TheClass
{
public:
  //! constructor
  TheClass() {}

private:
  //! member
  int M_member;
  //! another member
  int member_;
};

//! the function
void thefunction() {}
Feel++ used to promote /** */ but this is no longer the case. The comment style will be updated progressively to match the new style using //!

7. Declaring variables

  • Declare each variable on a separate line

  • Avoid short (e.g. a, rbarr, nughdeget) names whenever possible

  • Single character variable names are only okay for counters and temporaries, where the purpose of the variable is obvious

  • Wait when declaring a variable until it is needed

// Wrong
int a, b;
char __c, __d;

// Correct
int height;
int width;
char __nameOfThis;
char __nameOfThat;

  • Variables and functions start with a lower-case letter. Each consecutive word in a variable’s or function’s name starts with an upper-case letter

  • Avoid abbreviations

// Wrong
short Cntr; char ITEM_DELIM = '';

// Correct
short counter; char itemDelimiter = '';

  • Classes always start with an upper-case letter.

// Wrong
class meshAdaptation {};

// Correct
class MeshAdaptation {};

  • Non-static data members name of structures and classes always start with M_ . M stands for Member, or adding _ at the end of the member name. The rational behind this is for example :

    • to be able to immediately see that the data is a member of a class or a struct

    • to easily search and query-replace

// Wong
class meshAdaptation { std::vector directions; };

// Correct
class meshAdaptation { std::vector directions_; };

// Correct
class MeshAdaptation { std::vector M_directions; };

  • Static data members name of structures and classes always start with S_ . S stands for Static. The rational behind this is for example :

    • to be able to immediately see that the data is a static member of a class or a struct

    • to easily search and query-replace

// Wrong
class meshAdaptation { static std::vector directions; };

// Wrong
class meshAdaptation { static std::vector directions_; };

// Correct
class MeshAdaptation { static std::vector S_directions; };

8. Whitespace

  • Use blank lines to group statements together where suited

  • Always use only one blank line

  • Always use a single space after a keyword and before a curly brace.

// Correct
if (foo) { }

// Wrong
if(foo) { }

  • For pointers or references, always use a single space between the type and or &, but no space between the or & and the variable name.

char *x;
const std::string &myString;
const char * const y = "hello";

  • Surround binary operators with spaces.

  • No space after a cast.

  • Avoid C-style casts when possible.

// Wrong
char* blockOfMemory = (char* ) malloc(data.size());

// Correct
char *blockOfMemory = reinterpret_cast(malloc(data.size()));

9. Braces

  • As a base rule, the left curly brace goes on the same line as the start of the statement:

// Wrong
if (codec) { }

// Correct
if (codec) { }

  • Function implementations and class declarations always have the left brace on the start of a line:

static void foo(int g) { std::cout << g << "" }

class Moo { };

  • Use curly braces when the body of a conditional statement contains more than one line, and also if a single line statement is somewhat complex.

// Wrong
if (address.isEmpty()) { return false; }

for (int i = 0; i < 10; ++i) { std::cout << "i=" << i << ""; }

// Correct
if (address.isEmpty()) return false;

for (int i = 0; i < 10; ++i) std::cout << "=" << i << "";

  • Exception 1: Use braces also if the parent statement covers several lines / wraps

// Correct
if (address.isEmpty() || !isValid() || !codec)
{
    return false;
}
else
{
   return true;
}


// Wrong
if (address.isEmpty() || !isValid() || !codec) {
  return false;
}
else {
  return truel
}

  • Exception 2: Use braces also in if-then-else blocks where either the if-code or the else-code covers several lines

// Wrong
if (address.isEmpty())
  return false;
else
{
  std::cout << address << ""; ++it;
 }

// Correct
if (address.isEmpty())
{
    return false;
}
else
{
    std::cout << address << ""; ++it;
}

// Wrong
if (a) if (b) ... else ...

// Correct
if (a) { if (b) ... else ... }

  • Use curly braces when the body of a conditional statement is empty

// Wrong
while (a);

// Correct
while (a) {}

10. Parentheses

  • Use parentheses to group expressions:

// Wrong
if (a && b || c)

// Correct
if ((a && b) || c)

// Wrong
a + b & c

// Correct
(a + b) & c

11. Switch statements

  • The case labels are in the same column as the switch

  • Every case must have a break (or return) statement at the end or a comment to indicate that there’s intentionally no break, unless another case follows immediately.

switch (myEnum)
{
  case Value1:
    doSomething();
    break;
  case Value2:
  case Value3:
    doSomethingElse(); // fall through
  default:
    defaultHandling();
    break;
}

12. Line breaks

  • Keep lines shorter than 100 characters; insert breaks if necessary.

  • Commas go at the end of a broken line; operators start at the beginning of the new line. An operator at the end of the line is easy to not see if your editor is too narrow.

// Correct
if (longExpression + otherLongExpression + otherOtherLongExpression) { }

// Wrong
if (longExpression + otherLongExpression + otherOtherLongExpression) { }

13. Inheritance and the virtual keyword

When reimplementing a virtual method, do not put the virtual keyword in the header file.