1,072
edits
C++ style guide: Difference between revisions
Jump to navigation
Jump to search
m
Re-wording
m (→Formatting) |
m (Re-wording) |
||
| (6 intermediate revisions by 4 users not shown) | |||
| Line 22: | Line 22: | ||
some code formatting tools. Example indenting: | some code formatting tools. Example indenting: | ||
< | <syntaxhighlight lang="cpp"> | ||
if (have_args) | if (have_args) | ||
{ | { | ||
| Line 30: | Line 30: | ||
else | else | ||
idx.push_back (make_value_list (args, arg_nm, tmp)); | idx.push_back (make_value_list (args, arg_nm, tmp)); | ||
</ | </syntaxhighlight> | ||
If you have nested {{codeline|if}} statements, use extra braces for extra | If you have nested {{codeline|if}} statements, use extra braces for extra | ||
| Line 40: | Line 40: | ||
innermost braces enclosing the split. Example: | innermost braces enclosing the split. Example: | ||
< | <syntaxhighlight lang="cpp"> | ||
SVD::type type = ((nargout == 0 || nargout == 1) | SVD::type type = ((nargout == 0 || nargout == 1) | ||
? SVD::sigma_only | ? SVD::sigma_only | ||
: (nargin == 2) ? SVD::economy : SVD::std); | : (nargin == 2) ? SVD::economy : SVD::std); | ||
</ | </syntaxhighlight> | ||
=== Non indenting whitespace === | === Non indenting whitespace === | ||
| Line 57: | Line 57: | ||
Declarations of pointers have the '*' character cuddled with the name of the variable. | Declarations of pointers have the '*' character cuddled with the name of the variable. | ||
< | <syntaxhighlight lang="cpp"> | ||
unsigned int *pointer_variable; | unsigned int *pointer_variable; | ||
</ | </syntaxhighlight> | ||
However, references have the '&' character cuddled with the type of the variable. | However, references have the '&' character cuddled with the type of the variable. | ||
< | <syntaxhighlight lang="cpp"> | ||
unsigned int& reference_variable; | unsigned int& reference_variable; | ||
</ | </syntaxhighlight> | ||
=== Line Length === | === Line Length === | ||
| Line 77: | Line 77: | ||
Format function headers like this: | Format function headers like this: | ||
< | <syntaxhighlight lang="cpp"> | ||
static bool | static bool | ||
matches_patterns (const string_vector& patterns, int pat_idx, | matches_patterns (const string_vector& patterns, int pat_idx, | ||
int num_pat, const std::string& name) | int num_pat, const std::string& name) | ||
</ | </syntaxhighlight> | ||
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 102: | Line 102: | ||
* Do not declare anything on the std namespace; | * Do not declare anything on the std namespace; | ||
{{Code|namespace style on a .h file|< | {{Code|namespace style on a .h file|<syntaxhighlight lang="cpp"> | ||
// Note indentation | // Note indentation | ||
namespace octave | namespace octave | ||
| Line 115: | Line 115: | ||
} | } | ||
} | } | ||
</ | </syntaxhighlight>}} | ||
{{Code|namespace style on a .cc file|< | {{Code|namespace style on a .cc file|<syntaxhighlight lang="cpp"> | ||
// Note indentation and that functions are not defined | // Note indentation and that functions are not defined | ||
// as "octave::math::foo:foo" | // as "octave::math::foo:foo" | ||
| Line 130: | Line 130: | ||
} | } | ||
} | } | ||
</ | </syntaxhighlight>}} | ||
== Naming == | == Naming == | ||
| Line 181: | Line 181: | ||
=== 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 205: | Line 205: | ||
and requires approval from other maintainers. | and requires approval from other maintainers. | ||
<syntaxhighlight lang="cpp"> | |||
#if defined (HAVE_THIS_C14_FEATURE) | |||
// code that really needs it | |||
#else | |||
// alternative code in its absence | |||
#endif | |||
</syntaxhighlight> | |||
== Doxygen == | |||
Doxygen documentation can be a great help when developing octave however the current state has a lot of room for improvement. For more information about Doxygen in Octave look at [[Doxygen]]. | |||
=== Doxygen Style Guide === | |||
Doxygen allows for a variety of commenting styles. In order to maintain uniformity across the entire project the following rules should be applied: | |||
* For Doxygen comments use only {{codeline|//!}} and NOT {{codeline|/*! ... */}}, regardless of the size of the block comment | |||
* Use {{codeline|@}} for any [https://www.stack.nl/~dimitri/doxygen/manual/commands.html Doxygen Special Commands] | |||
* Use as little formatting as possible. Restrict to [https://www.stack.nl/~dimitri/doxygen/manual/markdown.html Markdown] and avoid HTML-markup. | |||
* Do NOT use the {{codeline|@brief}} command, the first sentence will automatically be used as the summary description. | |||
* The first sentence should describe briefly what the function does and end with a period. | |||
* Leave a blank line between the Doxygen comment and function definition. | |||
An example of properly used Doxygen would look like: | |||
<syntaxhighlight lang="cpp"> | |||
//! Does something interesting with its arguments. | |||
//! | |||
//! Long comment with **bold** special commands. | |||
//! | |||
//! @param some_param Really should figure out what to do. | |||
//! @param another_param Does something cool with @p some_param. | |||
//! | |||
//! And some example using syntax highlighting: | |||
//! | |||
//! @code{.cc} | |||
//! double v = 1.0; | |||
//! int n = 2; | |||
//! some_function (v, n); | |||
//! @endcode | |||
void | |||
some_function (double some_param, int another_param) | |||
{ | |||
// ... | |||
} | |||
</syntaxhighlight> | |||
== Comments == | == Comments == | ||