ExternalVendorCode/genode
1
0
Fork 0
mirror of https://github.com/genodelabs/genode.git synced 2024-12-18 21:27:56 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

doc: merge coding_style.txt into conventions.txt

Browse Source 
Issue #5393
This commit is contained in:
Norman Feske 2024-12-02 15:30:17 +01:00 committed by Christian Helmuth
parent f2c25383af
commit 979aaed52b
2 changed files with 308 additions and 344 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

299
doc/coding_style.txt
View File

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

353
doc/conventions.txt
View File

@ -1,70 +1,333 @@
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 We use the GOSH syntax [https://github.com/nfeske/gosh] for documentation and
README files. README files.
We encourage that each directory contains a file called 'README' that briefly
explains what the directory is about.
README files File names
############ ----------
Each directory should contain a file called 'README' that briefly explains All normal file names are lowercase. Filenames should be chosen to be
what the directory is about. In 'doc/Makefile' is a rule for expressive. Someone who explores your files for the first time might not
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.
Filenames
#########
All normal filenames 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 understand what 'mbi.cc' means but 'multiboot_info.cc' would ring a bell. If a
filename contains multiple words, use the '_' to separate them (instead of file name contains multiple words, use the '_' to separate them (instead of
'miscmath.h', use 'misc_math.h'). 'miscmath.h', use 'misc_math.h').
Coding style Coding style
############ ############
A common coding style helps a lot to ease collaboration. The official coding Things to avoid
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. 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 ! * \brief Short description of the file
provides the interfaces. ! * \author Original author
! * \date Creation date
Each RPC interface is represented by a separate include subdirectory. For ! *
an example, see 'base/include/ram_session/'. The header file that defines ! * Some more detailed description. This is optional.
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>/'.
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 Service names as announced via the 'parent()->announce()' function follow
the following convention: the following convention: