/usr/share/doc/openvdb/html/codingStyle.html is in libopenvdb-doc 2.1.0-1ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.6"/>
<title>OpenVDB: Coding Style</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">OpenVDB
 <span id="projectnumber">2.1.0</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.6 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="namespaces.html"><span>Namespaces</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
<div id="nav-path" class="navpath">
<ul>
<li class="navelem"><a class="el" href="index.html">OpenVDB</a></li> </ul>
</div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">Coding Style </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="Introduction"></a>
Introduction</h1>
<p>This document details the coding practices that are used in the OpenVDB codebase. Contributed code should conform to these guidelines to maintain consistency and maintainability. If there is a rule that you would like clarified, changed, or added, please send a note to <a href="#" onclick="location.href='mai'+'lto:'+'ope'+'nv'+'db@'+'gm'+'ail'+'.c'+'om'; return false;">openv<span style="display: none;">.nosp@m.</span>db@g<span style="display: none;">.nosp@m.</span>mail.<span style="display: none;">.nosp@m.</span>com</a>.</p>
<h1><a class="anchor" id="Contents"></a>
Contents</h1>
<ul>
<li><a class="el" href="codingStyle.html#sNamingConventions">Naming Conventions</a><ul>
<li><a class="el" href="codingStyle.html#sNamespaceConventions">Namespaces</a></li>
<li><a class="el" href="codingStyle.html#sClassConventions">Classes and Structs</a></li>
<li><a class="el" href="codingStyle.html#sClassMethods">Class Methods</a></li>
<li><a class="el" href="codingStyle.html#sClassInstanceVariables">Class Instance Variables</a></li>
<li><a class="el" href="codingStyle.html#sClassStaticVariables">Class Static Variables</a></li>
<li><a class="el" href="codingStyle.html#sLocalVariablesAndArguments">Local Variables and Arguments</a></li>
<li><a class="el" href="codingStyle.html#sConstants">Constants</a></li>
<li><a class="el" href="codingStyle.html#sEnumerationNames">Enumeration Names</a></li>
<li><a class="el" href="codingStyle.html#sEnumerationValues">Enumeration Values</a></li>
<li><a class="el" href="codingStyle.html#sTypedefs">Typedefs</a></li>
<li><a class="el" href="codingStyle.html#sGlobalVariables">Global Variables</a></li>
<li><a class="el" href="codingStyle.html#sGlobalFunctions">Global Functions</a></li>
<li><a class="el" href="codingStyle.html#sBooleans">Booleans</a></li>
</ul>
</li>
<li><a class="el" href="codingStyle.html#sPractices">Practices</a><ul>
<li><a class="el" href="codingStyle.html#sGeneral">General</a></li>
<li><a class="el" href="codingStyle.html#sFormatting">Formatting</a></li>
<li><a class="el" href="codingStyle.html#sIncludeStatements">Include Statements</a></li>
<li><a class="el" href="codingStyle.html#sComments">Comments</a></li>
<li><a class="el" href="codingStyle.html#sPrimitiveTypes">Primitive Types</a></li>
<li><a class="el" href="codingStyle.html#sMacros">Macros</a></li>
<li><a class="el" href="codingStyle.html#sClasses">Classes</a></li>
<li><a class="el" href="codingStyle.html#sConditionalStatements">Conditional Statements</a></li>
<li><a class="el" href="codingStyle.html#sNamespaces">Namespaces</a></li>
<li><a class="el" href="codingStyle.html#sExceptions">Exceptions</a></li>
<li><a class="el" href="codingStyle.html#sTemplates">Templates</a></li>
<li><a class="el" href="codingStyle.html#sMiscellaneous">Miscellaneous</a></li>
</ul>
</li>
</ul>
<h1><a class="anchor" id="sNamingConventions"></a>
Naming Conventions</h1>
<h2><a class="anchor" id="sNamespaceConventions"></a>
Namespaces</h2>
<ol type="1">
<li>Lowercase words, keep simple and short (e.g., <code>tools</code>, <code>tree</code>).</li>
</ol>
<h2><a class="anchor" id="sClassConventions"></a>
Classes and Structs</h2>
<ol type="1">
<li>Mixed case; first letter uppercase (e.g., <code>AffineMap</code>, <code>TreeIterator</code>)</li>
<li>Do not use a prefix.</li>
</ol>
<h2><a class="anchor" id="sClassMethods"></a>
Class Methods</h2>
<ol type="1">
<li>Mixed case; first letter lowercase (e.g., <code>getAccessor()</code>, <code>gridType()</code>)</li>
<li>Accessors that return a member variable by reference or a primitive type by value are just the variable name (e.g., <code>Grid::tree()</code>).</li>
<li>Accessors that involve construction of objects or other computations are <code>get</code> + the variable name (e.g., <code>Grid::getAccessor()</code>).</li>
<li>Simple mutators are <code>set</code> + the variable name (e.g., <code>Grid::setTree(tree);</code>).</li>
</ol>
<h2><a class="anchor" id="sClassInstanceVariables"></a>
Class Instance Variables</h2>
<ol type="1">
<li>Mixed case; always prefixed by <code>m</code> (e.g., <code>mTree</code>, <code>mTransform</code>)</li>
</ol>
<h2><a class="anchor" id="sClassStaticVariables"></a>
Class Static Variables</h2>
<ol type="1">
<li>Mixed case; always prefixed by <code>s</code> (e.g., <code>sInitialized</code>)</li>
</ol>
<h2><a class="anchor" id="sLocalVariablesAndArguments"></a>
Local Variables and Arguments</h2>
<ol type="1">
<li>Use mixed case with an initial lower case (e.g., <code>ijk</code>, <code>offset</code>, <code>range</code>, <code>rhsValue</code>).</li>
</ol>
<h2><a class="anchor" id="sConstants"></a>
Constants</h2>
<ol type="1">
<li>All uppercase; words separated by underscores. If not in a namespace or local to a source file, then prefixed with the library name in all caps (e.g., <code>HALF_FLOAT_TYPENAME_SUFFIX</code>, <code>ZIP_COMPRESSION_LEVEL</code>).</li>
</ol>
<h2><a class="anchor" id="sEnumerationNames"></a>
Enumeration Names</h2>
<ol type="1">
<li>Mixed case; first letter uppercase (e.g., <code>GridClass</code>, <code>VecType</code>)</li>
</ol>
<h2><a class="anchor" id="sEnumerationValues"></a>
Enumeration Values</h2>
<ol type="1">
<li>Same as constants; all uppercase; words separated by underscores (e.g., <code>GRID_LEVEL_SET</code>, <code>VEC_INVARIANT</code>) and with a common prefix (<code>GRID_</code>, <code>VEC_</code>, etc.)</li>
</ol>
<h2><a class="anchor" id="sTypedefs"></a>
Typedefs</h2>
<ol type="1">
<li>Mixed case; first letter uppercase (e.g., <code>ConstPtr</code>, <code>ValueType</code>)</li>
<li>Do not use a prefix.</li>
</ol>
<h2><a class="anchor" id="sGlobalVariables"></a>
Global Variables</h2>
<ol type="1">
<li>Mixed case; always prefixed by <code>g</code> (e.g., <code>gRegistry</code>)</li>
<li>In general, try to use class static data instead of globals.</li>
</ol>
<h2><a class="anchor" id="sGlobalFunctions"></a>
Global Functions</h2>
<ol type="1">
<li>Mixed case; always prefixed by <code>g</code> (e.g., <code>gFunc()</code>).</li>
<li>In general, try to use class static members instead of global functions.</li>
</ol>
<h2><a class="anchor" id="sBooleans"></a>
Booleans</h2>
<ol type="1">
<li>When naming boolean functions and variables, use names that read as a condition (e.g., <code>if (grid.empty())</code>, <code>if (<a class="el" href="namespaceopenvdb_1_1v2__1__0_1_1math.html#ac0a8a6cb53df253dc16aaec424bf9c71">matrix.isInvertible()</a>)</code>).</li>
</ol>
<h1><a class="anchor" id="sPractices"></a>
Practices</h1>
<h2><a class="anchor" id="sGeneral"></a>
General</h2>
<ol type="1">
<li>Code must compile without any warning messages. if closely related.</li>
<li>Prefer the C++ Standard Library to the C Standard Library.</li>
<li>Restrict variables to the smallest scopes possible, and avoid defining local variables before giving them values. Prefer declarations inside conditionals: <code>if (Grid::Ptr grid = <a class="el" href="namespaceopenvdb_1_1v2__1__0.html#ac43068080f663736cfc10a62c6a0827f" title="Create a new grid of type GridType with a given background value. ">createGrid()</a>) { ... }</code> instead of <code>Grid::Ptr grid = <a class="el" href="namespaceopenvdb_1_1v2__1__0.html#ac43068080f663736cfc10a62c6a0827f" title="Create a new grid of type GridType with a given background value. ">createGrid()</a>; if (grid) { ... }</code></li>
<li>For new files, be sure to use the right license boilerplate per our license policy.</li>
</ol>
<h2><a class="anchor" id="sFormatting"></a>
Formatting</h2>
<ol type="1">
<li>Use Doxygen-style comments to document public code.</li>
<li>Indentation is 4 spaces. Do not use tabs.</li>
<li>Use Unix-style carriage returns ("\n") rather than Windows/DOS ones ("\r\n").</li>
<li>Don’t put an <code>else</code> right after a <code>return</code>. It’s unnecessary and increases indentation level.</li>
<li>Do not leave debug printfs or other debugging code lying around.</li>
<li>Leave a blank line between a group of variable declarations and other code.</li>
<li>Leave a space after the keywords <code>if</code>, <code>switch</code>, <code>while</code>, <code>do</code>, <code>for</code>, and <code>return</code>.</li>
<li>Leave a space on each side of binary operators such as +, -, *, /, &&, and ||. For clarity in mathematical situations, you may omit the spaces on either side of * and / operators to illustrate their precedence over + and -.</li>
<li>Do not leave a space between any dereferencing operator (such as *, &, [], ->, or .) and its operands.</li>
<li>In parameter lists, leave a space after each comma.</li>
<li>Do not leave a space after an opening parenthesis or before a closing parenthesis.</li>
<li>Parentheses should be used to clarify operator precedence in expressions.</li>
<li>Do not leave a space before an end-of-statement semicolon.</li>
<li>Do not use literal tabs in strings or character constants. Rather, use spaces or "\t".</li>
<li>If a parameter list is too long, break it between parameters. Group related parameters on lines if appropriate.</li>
<li>Modified spacing is allowed to vertically align repetitive expressions.</li>
<li>Always begin numeric constants with a digit (e.g., 0.001 not .001).</li>
<li>Use K&R-style brace placement in public code.</li>
<li>You may leave off braces for simple, single line flow control statements.</li>
<li>The return type in a function definition should go on a line by itself.</li>
</ol>
<h2><a class="anchor" id="sIncludeStatements"></a>
Include Statements</h2>
<ol type="1">
<li>Always use double quotes ("") to include header files that live in the same directory as your source code.</li>
<li>Use angle brackets (<>) to include header files from outside a file’s directory.</li>
<li>Do not use absolute paths in include directives.</li>
<li>If there is a header corresponding to a given source file, list it first, followed by other local headers, library headers and then system headers.</li>
</ol>
<h2><a class="anchor" id="sHeaderFiles"></a>
Header Files</h2>
<ol type="1">
<li>Header files have a <code>.h</code> extension.</li>
<li>All header files should be bracketed by <code>#ifdef</code> "guard" statements.</li>
<li>In class definitions, list public, then protected, then private members.</li>
<li>List methods before variables.</li>
<li>Fully prototype all public functions and use descriptive naming for each argument.</li>
<li>Declare every function defined in a header but outside a class definition explicitly as <code>inline</code>.</li>
<li>Prefer forward declarations to <code>#include</code> directives in headers.</li>
<li>Do not take advantage of indirect inclusion of header files.</li>
</ol>
<h2><a class="anchor" id="sSourceFiles"></a>
Source Files</h2>
<ol type="1">
<li>Source files have a <code>.cc</code> extension.</li>
<li>Properly prototype all file static functions with usefully named arguments.</li>
<li>Whenever possible, put variables and functions in an anonymous namespace.</li>
<li>Avoid global variables.</li>
<li>For the main file of an executable, define <code>main()</code> at the top and then utility functions below it in a top-down fashion.</li>
</ol>
<h2><a class="anchor" id="sComments"></a>
Comments</h2>
<ol type="1">
<li>Use <code>//</code> style comments instead of / * * / style, even for multi-line comments.</li>
<li>Use multi-line comments to describe following paragraphs of code.</li>
<li>Use end-of-line comments to describe variable declarations or to clarify a single statement.</li>
<li>Large blocks of code should be commented out with <code>#if 0</code> and <code>#endif</code>.</li>
<li>Do not leave obsolete code fragments within comments as an historical trail.</li>
</ol>
<h2><a class="anchor" id="sPrimitiveTypes"></a>
Primitive Types</h2>
<ol type="1">
<li>Avoid writing code that is dependent on the bit size of primitive values, but when specific bit sizes are required, use explicitly-sized types such as <code>int32_t</code> or <code>uint64_t</code>.</li>
</ol>
<h2><a class="anchor" id="sMacros"></a>
Macros</h2>
<ol type="1">
<li>Avoid macros for constants. Use static constants instead.</li>
<li>Avoid macro functions. Use <code>inline</code> and templates instead.</li>
</ol>
<h2><a class="anchor" id="sClasses"></a>
Classes</h2>
<ol type="1">
<li>Constructors that can be called with only one argument should be prefixed with the <code>explicit</code> keyword to avoid unintended type conversions.</li>
<li>Always list the destructor.</li>
<li>Never call virtual methods from destructors.</li>
<li>If you have a copy constructor, make sure you have an assignment operator.</li>
<li>If you have an assignment operator, you probably need a copy constructor.</li>
<li>If you have data members that are pointers to dynamically allocated memory, make sure you have a copy constructor and an assignment operator, both of which do the right thing with that memory.</li>
<li>Classes which are to be subclassed always have a virtual destructor, even if it is empty.</li>
<li>Check against self assignment and return <code>*this</code> in assignment operators.</li>
<li>Declare methods as const as much as possible.</li>
<li>Declare object-valued input arguments as const references wherever possible. Primitives may be passed by value, however.</li>
<li>Arithmetic, logical, bitwise, dereference, and address of operators should only be used when their semantics are clear, obvious, and unambiguous.</li>
<li>The application operator [ () ] is allowed for functors.</li>
<li>Conversion operators should be avoided.</li>
<li>Never return const references to stack allocated or implicitly computed objects.</li>
<li>If a class does not have a copy constructor and/or assignment operator, consider creating a private unimplemented copy constructor and/or assignment operator to prevent automatically generated versions from being used.</li>
</ol>
<h2><a class="anchor" id="sConditionalStatements"></a>
Conditional Statements</h2>
<ol type="1">
<li>For test expressions, use a form that indicates as clearly as possible the types of operands by avoiding implicit casts.</li>
<li>Assignments that occur within conditional statements must have no effect in the enclosing scope.</li>
<li>Allow for arithmetic imprecision when comparing floating point values.</li>
<li>In switch statements, always comment fallthroughs and empty cases.</li>
</ol>
<h1><a class="anchor" id="sNamespaces"></a>
Namespaces</h1>
<ol type="1">
<li>Namespaces should be used whenever possible.</li>
<li>Avoid pulling in entire namespaces with <code>using</code> directives (e.g., <code>using namespace std;</code>).</li>
<li><code>using</code> declarations are allowed for individual symbols (e.g., <code>using std::vector;</code>), but they should never appear in a header file.</li>
<li>Define global operators in the namespace of their arguments.</li>
<li>Namespaces are not indented.</li>
</ol>
<h2><a class="anchor" id="sExceptions"></a>
Exceptions</h2>
<ol type="1">
<li>Appropriate use of exceptions is encouraged.</li>
<li>Methods should declare all exceptions they might throw using comments, but not exception specifications.</li>
<li>Throw scope local exception instances, not pointers or references or globals.</li>
<li>Catch exceptions by reference.</li>
<li>Never allow an exception to escape from a destructor.</li>
</ol>
<h2><a class="anchor" id="sTemplates"></a>
Templates</h2>
<ol type="1">
<li>Use <code>typename</code> rather than <code>class</code> when declaring template type parameters.</li>
</ol>
<h2><a class="anchor" id="sMiscellaneous"></a>
Miscellaneous</h2>
<ol type="1">
<li>Don’t use pointers to run through arrays of non-primitive types. Use explicit array indexing, iterators or generic algorithms instead.</li>
<li>Use C++ casts (<code>static_cast<int>(x)</code> or <code>int(x)</code>), not C casts (<code>(int)x</code>).</li>
<li>Multiple variables of the same data type may be declared on the same line</li>
<li>Library code must never deliberately terminate the application in response to an error condition.</li>
<li>Avoid using malloc/free when new/delete can be used instead.</li>
<li>Avoid <code>goto</code>.</li>
<li>Avoid "magic numbers". Use named constants when necessary.</li>
<li>If you use typeid/typeinfo, be aware that although all runtimes support <code>typeinfo::name()</code>, the format of the string it returns varies between compilers and even for a given compiler the value is not guaranteed to be unique. </li>
</ol>
</div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Fri Feb 7 2014 01:56:46 for OpenVDB by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.6
</small></address>
</body>
</html>
|