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. | |||
Example: | When indenting, indent the statement after control | ||
structures (like {{codeline|if}}, {{codeline|while}}, etc.). 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). This format is known as "GNU style" and is an option for | |||
some code formatting tools. Example indenting: | |||
< | <pre> | ||
if (have_args) | if (have_args) | ||
{ | { | ||
Line 61: | Line 30: | ||
else | else | ||
idx.push_back (make_value_list (args, arg_nm, tmp)); | idx.push_back (make_value_list (args, arg_nm, tmp)); | ||
</ | </pre> | ||
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 106: | Line 40: | ||
innermost braces enclosing the split. Example: | innermost braces enclosing the split. Example: | ||
< | <pre> | ||
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); | ||
</ | </pre> | ||
=== | === 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}}. | |||
=== 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: | |||
< | <pre> | ||
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) | ||
</ | </pre> | ||
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|<pre> | |||
// Note indentation | |||
{{Code| | namespace octave | ||
{ | |||
namespace math | |||
{ | |||
class foo | |||
{ | |||
public: | |||
foo (...); | |||
}; | |||
} | |||
} | |||
</ | </pre>}} | ||
{{Code|namespace style on a .cc file|<pre> | |||
// 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 202: | Line 118: | ||
} | } | ||
} | } | ||
</ | </pre>}} | ||
== 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 162: | ||
== 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. | |||
if | |||
=== std::string === | === std::string === | ||
When an empty string is required, use | When an empty string is required, use @qcode{""}, rather than creating an empty | ||
string object with | string object with @code{std::string ()}. | ||
=== auto === | === auto === | ||
Line 365: | Line 181: | ||
* 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++14 === | |||
=== 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. | |||
#if defined (HAVE_THIS_C14_FEATURE) | |||
// code that really needs it | |||
#else | |||
// alternative code in its absence | |||
#endif | |||
// | |||
== Comments == | == Comments == | ||
Line 434: | Line 205: | ||
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. | ||