C++ style guide: Difference between revisions

Jump to navigation Jump to search

C++ style guide (edit)

Revision as of 06:26, 10 June 2020

4,556 bytes added ,  10 June 2020
Add Category:Development.
(9 intermediate revisions by 6 users not shown)
Line 14: Line 14:
We use spaces for indentation. Absolutely do not use tabs in your code.
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.
You should probably set your editor to emit spaces when you hit the tab key.
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:
<syntaxhighlight lang="cpp">
if (have_args)
  {
    idx.push_back (first_args);
    have_args = false;
  }
else
  idx.push_back (make_value_list (args, arg_nm, tmp));
</syntaxhighlight>
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
with an operator rather than identifier.  If the split occurs inside
braces, continuation should be aligned with the first char after the
innermost braces enclosing the split.  Example:
<syntaxhighlight lang="cpp">
SVD::type type = ((nargout == 0 || nargout == 1)
                  ? SVD::sigma_only
                  : (nargin == 2) ? SVD::economy : SVD::std);
</syntaxhighlight>
=== Non indenting whitespace ===
Consider putting extra braces around a multi-line expression to make it
more readable, even if they are not necessary.  Also, do not hesitate to
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 name of the variable.
<syntaxhighlight lang="cpp">
unsigned int *pointer_variable;
</syntaxhighlight>
However, references have the '&' character cuddled with the type of the variable.
<syntaxhighlight lang="cpp">
unsigned int& reference_variable;
</syntaxhighlight>


=== Line Length ===
=== Line Length ===
Line 20: Line 72:
readability in the widest range of environments.  This is inherited from
readability in the widest range of environments.  This is inherited from
the [https://www.gnu.org/prep/standards/standards.html#Formatting GNU Coding Standards].
the [https://www.gnu.org/prep/standards/standards.html#Formatting GNU Coding Standards].
=== Function headers ===
Format function headers like this:
<syntaxhighlight lang="cpp">
static bool
matches_patterns (const string_vector& patterns, int pat_idx,
                  int num_pat, const std::string& name)
</syntaxhighlight>
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
multi-line argument lists should be aligned on the first char after the open
parenthesis.  You should put a space before the left open parenthesis and after
commas, for both function definitions and function calls.


=== Namespace ===
=== Namespace ===
Line 34: 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|<pre>
{{Code|namespace style on a .h file|<syntaxhighlight lang="cpp">
// Note indentation
// Note indentation
namespace octave
namespace octave
Line 47: Line 115:
   }
   }
}
}
</pre>}}
</syntaxhighlight>}}


{{Code|namespace style on a .cc file|<pre>
{{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 62: Line 130:
   }
   }
}
}
</pre>}}
</syntaxhighlight>}}
 
== Naming ==
 
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 98: Line 172:
Header files should not use any "#if defined (HAVE_FEATURE)" conditionals.  This is not quite true yet, but we are almost there.  '''No new conditionals may be added.'''
Header files should not use any "#if defined (HAVE_FEATURE)" conditionals.  This is not quite true yet, but we are almost there.  '''No new conditionals may be added.'''


== Other C++ features ==
== C++ features ==


=== C++11 ===
=== C++11 features ===


C++11 features are generally allowed. Check if the feature you want to
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.
use has been already used.  If not, ask on the mailing list.


==== auto ====
=== std::string ===
 
When an empty string is required, use "", rather than creating an empty
string object with std::string ().
 
=== auto ===


Use of {{codeline|auto}} is allowed only where it helps readability
Use of {{codeline|auto}} is allowed only where it helps readability
Line 126: Line 205:
and requires approval from other maintainers.
and requires approval from other maintainers.


#if defined (HAVE_THIS_C14_FEATURE)
<syntaxhighlight lang="cpp">
  // code that really needs it
#if defined (HAVE_THIS_C14_FEATURE)
#else
  // code that really needs it
  // alternative code in its absence
#else
#endif
  // 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 ==
 
=== FIXME notes ===
 
The preferred comment mark for places that may need further attention is
with {{codeline|FIXME:}} comments.
 
[[Category:Development]]
Retrieved from "https://wiki.octave.org/Special:MobileDiff/9498...13113"

Navigation menu