doc: improve coding-style descriptipn, fix #1468
This patch removes a broken link to an external blog posting and adds an example for the proper use of tabs and spaces instead.
This commit is contained in:
parent
1b155dbaa6
commit
9fcce49548
|
@ -18,16 +18,15 @@ macros.
|
||||||
! COLOR_GREEN = 3
|
! COLOR_GREEN = 3
|
||||||
! };
|
! };
|
||||||
|
|
||||||
:Meta-programming:
|
:Meta programming:
|
||||||
|
|
||||||
Use templates instead of pre-processor macros.
|
Use templates instead of pre-processor macros. In contrast to macros,
|
||||||
In contrast to macros, templates are type-safe
|
templates are type-safe and fit well with the implementation syntax.
|
||||||
and fit well with the implementation syntax.
|
|
||||||
|
|
||||||
:Conditional-code inclusion:
|
:Conditional-code inclusion:
|
||||||
|
|
||||||
Please avoid C-hacker style '#ifdef CONFIG_PLATFROM' - '#endif'
|
Please avoid C-hacker style '#ifdef CONFIG_PLATFROM' - '#endif'
|
||||||
constructs but instead, factor-out the encapsulated code into a
|
constructs. Instead, factor-out the encapsulated code into a
|
||||||
separate file and introduce a proper function interface.
|
separate file and introduce a proper function interface.
|
||||||
The build process should then be used to select the appropriate
|
The build process should then be used to select the appropriate
|
||||||
platform-specific files at compile time. Keep platform dependent
|
platform-specific files at compile time. Keep platform dependent
|
||||||
|
@ -50,17 +49,18 @@ Header of each file
|
||||||
Identifiers
|
Identifiers
|
||||||
===========
|
===========
|
||||||
|
|
||||||
* First character of class names uppercase, any other characters lowercase
|
* The first character of class names are uppercase, any other characters are
|
||||||
* Function and variable names lower case
|
lowercase.
|
||||||
* 'Multi_word_identifiers' via underline
|
* Function and variable names are lower case.
|
||||||
* 'CONSTANTS' upper case
|
* 'Multi_word_identifiers' use underline to separate words.
|
||||||
* Private and protected members of a class begin with an '_'-character
|
* 'CONSTANTS' and template arguments are upper case.
|
||||||
|
* Private and protected members of a class begin with an '_'-character.
|
||||||
* Accessor functions are named after their corresponding attributes:
|
* Accessor functions are named after their corresponding attributes:
|
||||||
|
|
||||||
! /**
|
! /**
|
||||||
! * Request private member variable
|
! * Request private member variable
|
||||||
! */
|
! */
|
||||||
! int value() { return _value; }
|
! int value() const { return _value; }
|
||||||
!
|
!
|
||||||
! /**
|
! /**
|
||||||
! * Set the private member variable
|
! * Set the private member variable
|
||||||
|
@ -73,14 +73,22 @@ Indentation
|
||||||
|
|
||||||
* Use one tab per indentation step. *Do not mix tabs and spaces!*
|
* Use one tab per indentation step. *Do not mix tabs and spaces!*
|
||||||
* Use no tabs except at the beginning of a line.
|
* Use no tabs except at the beginning of a line.
|
||||||
* Use spaces for alignment
|
* 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
|
||||||
|
|
||||||
See [http://web.archive.org/web/20050311153439/http://electroly.com/mt/archives/000002.html]
|
This way, each developer can set his preferred tab size in his editor
|
||||||
for a more detailed description.
|
|
||||||
|
|
||||||
This way, everyone can set his preferred tabsize in his editor
|
|
||||||
and the source code always looks good.
|
and the source code always looks good.
|
||||||
|
|
||||||
|
_Hint:_ In VIM, use the 'set list' and 'set listchars' commands to make tabs
|
||||||
|
and spaces visible.
|
||||||
|
|
||||||
|
|
||||||
Switch statements
|
Switch statements
|
||||||
~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~
|
||||||
|
@ -165,12 +173,13 @@ prepended by a header as follows:
|
||||||
! /**
|
! /**
|
||||||
! * Short description
|
! * Short description
|
||||||
! *
|
! *
|
||||||
! * \param a meaning of parameter a
|
! * \param a meaning of parameter a
|
||||||
! * \param b meaning of parameter b
|
! * \param b meaning of parameter b
|
||||||
! * \param c,d meaning of parameters c and d
|
! * \param c,d meaning of parameters c and d
|
||||||
! *
|
! *
|
||||||
! * \return meaning of return value
|
! * \throw Exception_type meaning of the exception
|
||||||
! * \retval 0 meaning of the return value 0
|
! *
|
||||||
|
! * \return meaning of return value
|
||||||
! *
|
! *
|
||||||
! * More detailed information about the function. This is optional.
|
! * More detailed information about the function. This is optional.
|
||||||
! */
|
! */
|
||||||
|
|
Loading…
Reference in New Issue