Coding style guidelines for Genode

Things to avoid

Please avoid using pre-processor macros. C++ provides language features for almost any case, for which a C programmer uses macros.

Defining constants

Use enum instead of #define

 enum { MAX_COLORS = 3 };
 enum {
   COLOR_RED   = 1,
   COLOR_BLUE  = 2,
   COLOR_GREEN = 3
 };

Meta programming

Use templates instead of pre-processor macros. In contrast to macros, templates are type-safe and fit well with the implementation syntax.

Conditional-code inclusion

Please avoid C-hacker style #ifdef CONFIG_PLATFROM - #endif constructs. Instead, factor-out the encapsulated code into a separate file and introduce a proper function interface. The build process should then be used to select the appropriate platform-specific files at compile time. Keep platform dependent code as small as possible. Never pollute existing generic code with platform-specific code.

Header of each file

 /*
  * \brief  Short description of the file
  * \author Original author
  * \date   Creation date
  *
  * Some more detailed description. This is optional.
  */

Identifiers

The first character of class names are uppercase, any other characters are lowercase.
Function and variable names are lower case.
Multi_word_identifiers use underline to separate words.
CONSTANTS and template arguments are upper case.
Private and protected members of a class begin with an _-character.

Accessor methods are named after their corresponding attributes:

 /**
  * Request private member variable
  */
 int value() const { return _value; }

 /**
  * Set the private member variable
  */
 void value(int value) { _value = value; }

Accessors that return a boolean value do not carry an is_ prefix. E.g., a method for requesting the validity of an object should be named valid(), not is_valid().

Indentation

Use one tab per indentation step. Do not mix tabs and spaces!
Use no tabs except at the beginning of a line.
Use spaces for the alignment of continuation lines such as function arguments that span multiple lines. The alignment spaces of such lines should start after the (tab-indented) indentation level. For example:
```
 {
 <tab>function_with_many_arguments(arg1,
 <tab><--- spaces for aligment --->arg2,
      ...
 }
```
Remove trailing spaces at the end of lines

This way, each developer can set his preferred tab size in his editor and the source code always looks good.

Hint: In VIM, use the set list and set listchars commands to make tabs and spaces visible.

If class initializers span multiple lines, put the colon on a separate line and indent the initializers using one tab. For example:

 Complicated_machinery(Material &material, Deadline deadline)
 :
 <tab>_material(material),
 <tab>_deadline(deadline),
 <tab>...
 {
      ...
 }

Preferably place statements that alter the control flow - such as break, continue, or return - at the beginning of a separate line, followed by vertical space (a blank line or the closing brace of the surrounding scope).
```
 if (early_return_possible)
     return;
```

Switch statements

Switch-statement blocks should be indented as follows:

 switch (color) {

 case BLUE:
 <tab>break;

 case GREEN:
 <tab>{
 <tab><tab>int declaration_required;
 <tab><tab>...
 <tab>}

 default:
 }

Please note that the case labels have the same indentation level as the switch statement. This avoids a two-level indentation-change at the end of the switch block that would occur otherwise.

Vertical whitespaces

In header files:

Leave two empty lines between classes.
Leave one empty line between member functions.

In implementation files:

Leave two empty lines between functions.

Braces

Braces after class, struct and function names are placed at a new line:
```
 class Foo
 {
   public:

     void method(void)
     {
       ...
     }
 };
```
except for one-line functions.
All other occurrences of open braces (for if, while, do, for, namespace, enum etc.) are at the end of a line:
```
 if (flag) {
   ..
 } else {
   ..
 }
```
One-line functions should be written on a single line as long as the line length does not exceed approximately 80 characters. Typically, this applies for accessor functions. If slightly more space than one line is needed, indent as follows:
```
 int heavy_computation(int a, int lot, int of, int args) {
   return a + lot + of + args; }
```

Comments

Function/method header

Each public or protected (but no private) method in a header-file should be prepended by a header as follows:

 /**
  * Short description
  *
  * \param a    meaning of parameter a
  * \param b    meaning of parameter b
  * \param c,d  meaning of parameters c and d
  *
  * \throw Exception_type  meaning of the exception
  *
  * \return meaning of return value
  *
  * More detailed information about the function. This is optional.
  */

Descriptions of parameters and return values should be lower-case and brief. More elaborative descriptions can be documented in the text area below.

In implementation files, only local and private functions should feature function headers.

Single-line comments

 /* use this syntax for single line comments */

A single-line comment should be prepended by an empty line. Single-line comments should be short - no complete sentences. Use lower-case.

C++-style comments (//) should only be used for temporarily commenting-out code. Such commented-out garbage is easy to grep and there are handy vim-macros available for creating and removing such comments.

Variable descriptions

Use the same syntax as for single-line comments. Insert two or more spaces before your comment starts.

 int size;   /* in kilobytes */

Multi-line comments

Multi-line comments are more detailed descriptions in the form of sentences. A multi-line comment should be enclosed by empty lines.

 /*
  * This is some tricky
  * algorithm that works
  * as follows:
  * ...
  */

The first and last line of a multi-line comment contain no words.

Source-code blocks

For structuring your source code, you can entitle the different parts of a file like this:

 <- two empty lines

 /********************
  ** Event handlers **
  ********************/
 <- one empty line

Note the two stars at the left and right. There are two of them to make the visible width of the border match its height (typically, characters are ca. twice as high as wide).

A source-code block header represents a headline for the following code. To couple this headline with the following code closer than with previous code, leave two empty lines above and one empty line below the source-code block header.

Order of public, protected, and private blocks

For consistency reasons, use the following class layout:

 class Sandstein
 {
   private:
     ...
   protected:
     ...
   public:
 };

Typically, the private section contains member variables that are used by public accessor functions below. In this common case, we only reference symbols that are defined above as it is done when programming plain C.

Leave one empty line (or a line that contains only a brace) above and below a private, protected, or public label. This also applies when the label is followed by a source-code block header.

Sections