Editing C++ style guide
Jump to navigation
Jump to search
The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then publish the changes below to finish undoing the edit.
Latest revision | Your text | ||
Line 7: | Line 7: | ||
== Formatting == | == Formatting == | ||
=== Indentation === | === Indentation === | ||
Use only spaces, and indent 2 spaces at a time. | |||
We use spaces for indentation. Absolutely do not use tabs in your code. | |||
You should probably set your editor to emit spaces when you hit the tab key. | |||
If there is a compound statement, indent ''both'' the curly braces and the body of the statement (so that the body gets indented by ''two'' indents). | When indenting, indent the statement after control | ||
structures (like {{codeline|if}}, {{codeline|while}}, etc.). If there | |||
Example: | is a compound statement, indent ''both'' the curly braces and the | ||
body of the statement (so that the body gets indented by ''two'' | |||
indents). This format is known as "GNU style" and is an option for | |||
some code formatting tools. Example indenting: | |||
<syntaxhighlight lang="cpp"> | <syntaxhighlight lang="cpp"> | ||
Line 63: | Line 32: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
If you have nested {{codeline|if}} statements, use extra braces for extra clarification. | If you have nested {{codeline|if}} statements, use extra braces for extra | ||
clarification. | |||
Split long expressions in such a way that a continuation line starts | Split long expressions in such a way that a continuation line starts | ||
Line 112: | Line 46: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
=== | === Non indenting whitespace === | ||
Consider putting extra braces around a multi-line expression to make it | Consider putting extra braces around a multi-line expression to make it | ||
Line 118: | Line 52: | ||
put extra braces anywhere if it improves clarity. | put extra braces anywhere if it improves clarity. | ||
The negation operator is written with a space between the operator | |||
and its target, e.g., {{codeline|! A}}. | |||
Declarations of pointers have the '*' character cuddled with the | Declarations of pointers have the '*' character cuddled with the name of the variable. | ||
<syntaxhighlight lang="cpp"> | <syntaxhighlight lang="cpp"> | ||
Line 126: | Line 61: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
However, references have the '&' character cuddled with the | However, references have the '&' character cuddled with the type of the variable. | ||
<syntaxhighlight lang="cpp"> | <syntaxhighlight lang="cpp"> | ||
Line 132: | Line 67: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
=== | === Line Length === | ||
Keep the length of source lines to 79 characters or less, for maximum | |||
readability in the widest range of environments. This is inherited from | |||
the [https://www.gnu.org/prep/standards/standards.html#Formatting GNU Coding Standards]. | |||
=== Function headers === | === Function headers === | ||
Format function headers like this: | |||
<syntaxhighlight lang="cpp"> | <syntaxhighlight lang="cpp"> | ||
Line 149: | Line 85: | ||
The return type of the function and any modifiers are specified on the first | The return type of the function and any modifiers are specified on the first | ||
line. The function name on the second line should start in column 1, and | line. The function name on the second line should start in column 1, and | ||
multi-line argument lists should be aligned on the first | multi-line argument lists should be aligned on the first char after the open | ||
parenthesis. | parenthesis. You should put a space before the left open parenthesis and after | ||
commas, for both function definitions and function calls. | commas, for both function definitions and function calls. | ||
=== Namespace === | === Namespace === | ||
All code should be in the | All code should be in the octave namespace. This is an ongoing project. We | ||
are still moving existing classes into namespaces but all new classes | |||
should go somewhere into the "octave" namespace. There is 1 extra level for namespaces | |||
inside octave to be used with care, we don't want too many namespaces. | |||
Ask before creating a new namespace. | |||
* Indent namespaces as any other block. Emacs and other editors can do this automatically. | |||
* Define namespace on the .cc files; | |||
* Do not use "using X" directives; | |||
* Do not declare anything on the std namespace; | |||
{{Code|namespace style on a .h file|<syntaxhighlight lang="cpp"> | |||
// Note indentation | |||
{{Code| | namespace octave | ||
{ | |||
namespace math | |||
{ | |||
class foo | |||
{ | |||
public: | |||
foo (...); | |||
}; | |||
} | |||
} | |||
</syntaxhighlight>}} | </syntaxhighlight>}} | ||
{{Code|namespace style on a .cc file|<syntaxhighlight lang="cpp"> | |||
// Note indentation and that functions are not defined | |||
{{Code| | // as "octave::math::foo:foo" | ||
// Note indentation and that functions are not defined as "octave::math::foo:foo" | |||
namespace octave | namespace octave | ||
{ | { | ||
Line 203: | Line 131: | ||
} | } | ||
</syntaxhighlight>}} | </syntaxhighlight>}} | ||
== Naming == | == Naming == | ||
Use lowercase names if possible. Uppercase is acceptable for variable names consisting of 1-2 letters. Do not use mixed case | Use lowercase names if possible. Uppercase is acceptable for variable | ||
names consisting of 1-2 letters. Do not use mixed case names. | |||
== Header Files == | == Header Files == | ||
Line 260: | Line 174: | ||
== C++ features == | == C++ features == | ||
=== | === C++11 features === | ||
C++11 features are generally allowed. Check if the feature you want to | |||
use has been already used. If not, ask on the mailing list. | |||
=== std::string === | === std::string === | ||
When an empty string is required, use | When an empty string is required, use "", rather than creating an empty | ||
string object with | string object with std::string (). | ||
=== auto === | === auto === | ||
Line 365: | Line 193: | ||
* Beware of copy when using {{codeline|auto}} in for loops. Pass by reference and use {{codeline|const}} unless you're dealing with simple types such as {{codeline|int}}. See [http://lists.gnu.org/archive/html/octave-maintainers/2016-06/msg00144.html 'auto' uses and for-range loops] on the maintainers mailing list for more details. | * Beware of copy when using {{codeline|auto}} in for loops. Pass by reference and use {{codeline|const}} unless you're dealing with simple types such as {{codeline|int}}. See [http://lists.gnu.org/archive/html/octave-maintainers/2016-06/msg00144.html 'auto' uses and for-range loops] on the maintainers mailing list for more details. | ||
=== C++ | === C++14 === | ||
Do not use C++14 features. Octave is widely used in very old systems and we | |||
want them to be able to use up to date versions of Octave. Building a recent | |||
compiler in such systems is not a trivial task so the limitation must happen | |||
in Octave. | in Octave. | ||
An exception: code that requires C++14 feature must also implement an | |||
alternative code in the absence of said feature. In such case, use a | |||
configure check. This increases maintenance a lot, must be used sparsely, | |||
and requires approval from other maintainers. | |||
<syntaxhighlight lang="cpp"> | <syntaxhighlight lang="cpp"> | ||
Line 434: | Line 259: | ||
The preferred comment mark for places that may need further attention is | The preferred comment mark for places that may need further attention is | ||
with {{codeline|FIXME:}} comments. | with {{codeline|FIXME:}} comments. | ||