genode/doc/conventions.txt

              ==================================================
              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.

: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.


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.