From 979aaed52b402e6490ebe436c58c67bf8e6a6c77 Mon Sep 17 00:00:00 2001 From: Norman Feske Date: Mon, 2 Dec 2024 15:30:17 +0100 Subject: [PATCH] doc: merge coding_style.txt into conventions.txt Issue #5393 --- doc/coding_style.txt | 299 ------------------------------------ doc/conventions.txt | 353 +++++++++++++++++++++++++++++++++++++------ 2 files changed, 308 insertions(+), 344 deletions(-) delete mode 100644 doc/coding_style.txt diff --git a/doc/coding_style.txt b/doc/coding_style.txt deleted file mode 100644 index 007b77b15c..0000000000 --- a/doc/coding_style.txt +++ /dev/null @@ -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: - ! { - ! function_with_many_arguments(arg1, - ! <--- 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) - ! : - ! _material(material), - ! _deadline(deadline), - ! ... - ! { - ! ... - ! } - -* 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: -! break; -! -! case GREEN: -! { -! int declaration_required; -! ... -! } -! -! 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. diff --git a/doc/conventions.txt b/doc/conventions.txt index 50b3130ed0..124211dc3d 100644 --- a/doc/conventions.txt +++ b/doc/conventions.txt @@ -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 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 -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. - - -Filenames -######### - -All normal filenames are lowercase. Filenames should be chosen to be -expressive. Someone who explores your files for the first time might not +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 -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'). 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 '/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//'. +! /* +! * \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: + ! { + ! function_with_many_arguments(arg1, + ! <--- 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) + ! : + ! _material(material), + ! _deadline(deadline), + ! ... + ! { + ! ... + ! } + +* 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: +! break; +! +! case GREEN: +! { +! int declaration_required; +! ... +! } +! +! 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: