1,072
edits
m (→Doxygen Style Guide: Apply the rest of the guide ;-)) |
m (Tweak type casting language) |
||
(5 intermediate revisions by 4 users not shown) | |||
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 192: | Line 192: | ||
* Do not use {{codeline|auto}} unless the type really is obscure. | * Do not use {{codeline|auto}} unless the type really is obscure. | ||
* 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++ style casting === | |||
Always use one of the four C++ long style casting forms ({{codeline|static_cast}}, {{codeline|dynamic_cast}}, {{codeline|reinterpret_cast}}, {{codeline|const_cast}}) rather than C-style forms (type cast {{codeline|(new_type) variable}} or the function form {{codeline|new_type (variable)}}). | |||
=== C++14 === | === C++14 === | ||
Line 221: | Line 225: | ||
Doxygen allows for a variety of commenting styles. In order to maintain uniformity across the entire project the following rules should be applied: | 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|/*! ... */}} | * 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 {{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. | * 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. | * Leave a blank line between the Doxygen comment and function definition. | ||
Line 229: | Line 235: | ||
<syntaxhighlight lang="cpp"> | <syntaxhighlight lang="cpp"> | ||
//! | //! Does something interesting with its arguments. | ||
//! | //! | ||
//! Long comment with **bold** special commands. | //! Long comment with **bold** special commands. | ||
Line 257: | Line 263: | ||
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. | ||
[[Category:Development]] |
edits