mirror of
https://github.com/genodelabs/genode.git
synced 2024-12-18 21:27:56 +00:00
Norman Feske
Christian Helmuth
parent
f2c25383af
commit
979aaed52b
@ -1,299 +0,0 @@
|
||||
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.
|
||||
@ -1,32 +1,22 @@
|
||||
|
||||
Conventions for the Genode development
|
||||
|
||||
|
||||
Norman Feske
|
||||
==================================================
|
||||
Conventions and coding-style guidelines for Genode
|
||||
==================================================
|
||||
|
||||
|
||||
Documentation
|
||||
#############
|
||||
|
||||
Documentation and naming of files
|
||||
#################################
|
||||
|
||||
We use the GOSH syntax [https://github.com/nfeske/gosh] for documentation and
|
||||
README files.
|
||||
|
||||
|
||||
README files
|
||||
############
|
||||
|
||||
Each directory should contain a file called 'README' that briefly explains
|
||||
what the directory is about. In 'doc/Makefile' is a rule for
|
||||
generating a directory overview from the 'README' files automatically.
|
||||
|
||||
You can structure your 'README' file by using the GOSH style for subsections:
|
||||
! Subsection
|
||||
! ~~~~~~~~~~
|
||||
Do not use chapters or sections in your '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
|
||||
@ -38,33 +28,306 @@ filename contains multiple words, use the '_' to separate them (instead of
|
||||
Coding style
|
||||
############
|
||||
|
||||
A common coding style helps a lot to ease collaboration. The official coding
|
||||
style of the Genode base components is described in 'doc/coding_style.txt'.
|
||||
If you consider working closely together with the Genode main developers,
|
||||
your adherence to this style is greatly appreciated.
|
||||
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.
|
||||
|
||||
|
||||
Include files and RPC interfaces
|
||||
################################
|
||||
Header of each file
|
||||
===================
|
||||
|
||||
Never place include files directly into the '<repository>/include/' directory
|
||||
but use a meaningful subdirectory that corresponds to the component that
|
||||
provides the interfaces.
|
||||
|
||||
Each RPC interface is represented by a separate include subdirectory. For
|
||||
an example, see 'base/include/ram_session/'. The header file that defines
|
||||
the RPC function interface has the same base name as the directory. The RPC
|
||||
stubs are called 'client.h' and 'server.h'. If your interface uses a custom
|
||||
capability type, it is defined in 'capability.h'. Furthermore, if your
|
||||
interface is a session interface of a service, it is good practice to
|
||||
provide a connection class in a 'connection.h' file for managing session-
|
||||
construction arguments and the creation and destruction of sessions.
|
||||
|
||||
Specialization-dependent include directories are placed in 'include/<specname>/'.
|
||||
! /*
|
||||
! * \brief Short description of the file
|
||||
! * \author Original author
|
||||
! * \date Creation date
|
||||
! *
|
||||
! * Some more detailed description. This is optional.
|
||||
! */
|
||||
|
||||
|
||||
Service Names
|
||||
#############
|
||||
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:
|
||||
|
||||
Loading…
Reference in New Issue
Block a user