Conventions and coding-style guidelines for Genode

Documentation and naming of files

We use the GOSH syntax https://github.com/nfeske/gosh for documentation and README files.

We encourage that each directory contains a file called README that briefly explains what the directory is about.

File names

All normal file names are lowercase. Filenames should be chosen to be expressive. Someone who explores your files for the first time might not understand what mbi.cc means but multiboot_info.cc would ring a bell. If a file name contains multiple words, use the _ to separate them (instead of miscmath.h, use misc_math.h).

Coding style

Things to avoid

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

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 (color) {

 case BLUE:
 <tab>break;

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

 default:
 }

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

 /**
  * 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.
  */

Single-line comments

 /* use this syntax for single line comments */

Variable descriptions

 int size;   /* in kilobytes */

Multi-line comments

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

Source-code blocks

 <- two empty lines

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

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.

Naming of Genode services

Service names as announced via the parent()->announce() function follow the following convention:

Core's services, which are the most fundamental base services are written completely upper case. Each developer should be aware of the meaning of the used acronyms such as RAM, RM, ROM. All other service names should be descriptive names rather than acronyms. Service names should contain only letters, numbers, and underline characters. The first character must always be an uppercase letter, all other characters are lowercase.