| 1 |
742 |
jeremybenn |
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
| 2 |
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
| 3 |
|
|
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Coding Style</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><meta name="keywords" content=" ISO C++ , runtime , library "/><link rel="home" href="../index.html" title="The GNU C++ Library"/><link rel="up" href="appendix_contributing.html" title="Appendix A. Contributing"/><link rel="prev" href="source_organization.html" title="Directory Layout and Source Conventions"/><link rel="next" href="source_design_notes.html" title="Design Notes"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Coding Style</th></tr><tr><td align="left"><a accesskey="p" href="source_organization.html">Prev</a> </td><th width="60%" align="center">Appendix A.
|
| 4 |
|
|
Contributing
|
| 5 |
|
|
|
| 6 |
|
|
</th><td align="right"> <a accesskey="n" href="source_design_notes.html">Next</a></td></tr></table><hr/></div><div class="section" title="Coding Style"><div class="titlepage"><div><div><h2 class="title"><a id="contrib.coding_style"/>Coding Style</h2></div></div></div><p>
|
| 7 |
|
|
</p><div class="section" title="Bad Identifiers"><div class="titlepage"><div><div><h3 class="title"><a id="coding_style.bad_identifiers"/>Bad Identifiers</h3></div></div></div><p>
|
| 8 |
|
|
Identifiers that conflict and should be avoided.
|
| 9 |
|
|
</p><div class="literallayout"><p><br/>
|
| 10 |
|
|
This is the list of names <span class="quote">“<span class="quote">reserved to the<br/>
|
| 11 |
|
|
implementation</span>”</span> that have been claimed by certain<br/>
|
| 12 |
|
|
compilers and system headers of interest, and should not be used<br/>
|
| 13 |
|
|
in the library. It will grow, of course. We generally are<br/>
|
| 14 |
|
|
interested in names that are not all-caps, except for those like<br/>
|
| 15 |
|
|
"_T"<br/>
|
| 16 |
|
|
<br/>
|
| 17 |
|
|
For Solaris:<br/>
|
| 18 |
|
|
_B<br/>
|
| 19 |
|
|
_C<br/>
|
| 20 |
|
|
_L<br/>
|
| 21 |
|
|
_N<br/>
|
| 22 |
|
|
_P<br/>
|
| 23 |
|
|
_S<br/>
|
| 24 |
|
|
_U<br/>
|
| 25 |
|
|
_X<br/>
|
| 26 |
|
|
_E1<br/>
|
| 27 |
|
|
..<br/>
|
| 28 |
|
|
_E24<br/>
|
| 29 |
|
|
<br/>
|
| 30 |
|
|
Irix adds:<br/>
|
| 31 |
|
|
_A<br/>
|
| 32 |
|
|
_G<br/>
|
| 33 |
|
|
<br/>
|
| 34 |
|
|
MS adds:<br/>
|
| 35 |
|
|
_T<br/>
|
| 36 |
|
|
<br/>
|
| 37 |
|
|
BSD adds:<br/>
|
| 38 |
|
|
__used<br/>
|
| 39 |
|
|
__unused<br/>
|
| 40 |
|
|
__inline<br/>
|
| 41 |
|
|
_Complex<br/>
|
| 42 |
|
|
__istype<br/>
|
| 43 |
|
|
__maskrune<br/>
|
| 44 |
|
|
__tolower<br/>
|
| 45 |
|
|
__toupper<br/>
|
| 46 |
|
|
__wchar_t<br/>
|
| 47 |
|
|
__wint_t<br/>
|
| 48 |
|
|
_res<br/>
|
| 49 |
|
|
_res_ext<br/>
|
| 50 |
|
|
__tg_*<br/>
|
| 51 |
|
|
<br/>
|
| 52 |
|
|
SPU adds:<br/>
|
| 53 |
|
|
__ea<br/>
|
| 54 |
|
|
<br/>
|
| 55 |
|
|
For GCC:<br/>
|
| 56 |
|
|
<br/>
|
| 57 |
|
|
[Note that this list is out of date. It applies to the old<br/>
|
| 58 |
|
|
name-mangling; in G++ 3.0 and higher a different name-mangling is<br/>
|
| 59 |
|
|
used. In addition, many of the bugs relating to G++ interpreting<br/>
|
| 60 |
|
|
these names as operators have been fixed.]<br/>
|
| 61 |
|
|
<br/>
|
| 62 |
|
|
The full set of __* identifiers (combined from gcc/cp/lex.c and<br/>
|
| 63 |
|
|
gcc/cplus-dem.c) that are either old or new, but are definitely<br/>
|
| 64 |
|
|
recognized by the demangler, is:<br/>
|
| 65 |
|
|
<br/>
|
| 66 |
|
|
__aa<br/>
|
| 67 |
|
|
__aad<br/>
|
| 68 |
|
|
__ad<br/>
|
| 69 |
|
|
__addr<br/>
|
| 70 |
|
|
__adv<br/>
|
| 71 |
|
|
__aer<br/>
|
| 72 |
|
|
__als<br/>
|
| 73 |
|
|
__alshift<br/>
|
| 74 |
|
|
__amd<br/>
|
| 75 |
|
|
__ami<br/>
|
| 76 |
|
|
__aml<br/>
|
| 77 |
|
|
__amu<br/>
|
| 78 |
|
|
__aor<br/>
|
| 79 |
|
|
__apl<br/>
|
| 80 |
|
|
__array<br/>
|
| 81 |
|
|
__ars<br/>
|
| 82 |
|
|
__arshift<br/>
|
| 83 |
|
|
__as<br/>
|
| 84 |
|
|
__bit_and<br/>
|
| 85 |
|
|
__bit_ior<br/>
|
| 86 |
|
|
__bit_not<br/>
|
| 87 |
|
|
__bit_xor<br/>
|
| 88 |
|
|
__call<br/>
|
| 89 |
|
|
__cl<br/>
|
| 90 |
|
|
__cm<br/>
|
| 91 |
|
|
__cn<br/>
|
| 92 |
|
|
__co<br/>
|
| 93 |
|
|
__component<br/>
|
| 94 |
|
|
__compound<br/>
|
| 95 |
|
|
__cond<br/>
|
| 96 |
|
|
__convert<br/>
|
| 97 |
|
|
__delete<br/>
|
| 98 |
|
|
__dl<br/>
|
| 99 |
|
|
__dv<br/>
|
| 100 |
|
|
__eq<br/>
|
| 101 |
|
|
__er<br/>
|
| 102 |
|
|
__ge<br/>
|
| 103 |
|
|
__gt<br/>
|
| 104 |
|
|
__indirect<br/>
|
| 105 |
|
|
__le<br/>
|
| 106 |
|
|
__ls<br/>
|
| 107 |
|
|
__lt<br/>
|
| 108 |
|
|
__max<br/>
|
| 109 |
|
|
__md<br/>
|
| 110 |
|
|
__method_call<br/>
|
| 111 |
|
|
__mi<br/>
|
| 112 |
|
|
__min<br/>
|
| 113 |
|
|
__minus<br/>
|
| 114 |
|
|
__ml<br/>
|
| 115 |
|
|
__mm<br/>
|
| 116 |
|
|
__mn<br/>
|
| 117 |
|
|
__mult<br/>
|
| 118 |
|
|
__mx<br/>
|
| 119 |
|
|
__ne<br/>
|
| 120 |
|
|
__negate<br/>
|
| 121 |
|
|
__new<br/>
|
| 122 |
|
|
__nop<br/>
|
| 123 |
|
|
__nt<br/>
|
| 124 |
|
|
__nw<br/>
|
| 125 |
|
|
__oo<br/>
|
| 126 |
|
|
__op<br/>
|
| 127 |
|
|
__or<br/>
|
| 128 |
|
|
__pl<br/>
|
| 129 |
|
|
__plus<br/>
|
| 130 |
|
|
__postdecrement<br/>
|
| 131 |
|
|
__postincrement<br/>
|
| 132 |
|
|
__pp<br/>
|
| 133 |
|
|
__pt<br/>
|
| 134 |
|
|
__rf<br/>
|
| 135 |
|
|
__rm<br/>
|
| 136 |
|
|
__rs<br/>
|
| 137 |
|
|
__sz<br/>
|
| 138 |
|
|
__trunc_div<br/>
|
| 139 |
|
|
__trunc_mod<br/>
|
| 140 |
|
|
__truth_andif<br/>
|
| 141 |
|
|
__truth_not<br/>
|
| 142 |
|
|
__truth_orif<br/>
|
| 143 |
|
|
__vc<br/>
|
| 144 |
|
|
__vd<br/>
|
| 145 |
|
|
__vn<br/>
|
| 146 |
|
|
<br/>
|
| 147 |
|
|
SGI badnames:<br/>
|
| 148 |
|
|
__builtin_alloca<br/>
|
| 149 |
|
|
__builtin_fsqrt<br/>
|
| 150 |
|
|
__builtin_sqrt<br/>
|
| 151 |
|
|
__builtin_fabs<br/>
|
| 152 |
|
|
__builtin_dabs<br/>
|
| 153 |
|
|
__builtin_cast_f2i<br/>
|
| 154 |
|
|
__builtin_cast_i2f<br/>
|
| 155 |
|
|
__builtin_cast_d2ll<br/>
|
| 156 |
|
|
__builtin_cast_ll2d<br/>
|
| 157 |
|
|
__builtin_copy_dhi2i<br/>
|
| 158 |
|
|
__builtin_copy_i2dhi<br/>
|
| 159 |
|
|
__builtin_copy_dlo2i<br/>
|
| 160 |
|
|
__builtin_copy_i2dlo<br/>
|
| 161 |
|
|
__add_and_fetch<br/>
|
| 162 |
|
|
__sub_and_fetch<br/>
|
| 163 |
|
|
__or_and_fetch<br/>
|
| 164 |
|
|
__xor_and_fetch<br/>
|
| 165 |
|
|
__and_and_fetch<br/>
|
| 166 |
|
|
__nand_and_fetch<br/>
|
| 167 |
|
|
__mpy_and_fetch<br/>
|
| 168 |
|
|
__min_and_fetch<br/>
|
| 169 |
|
|
__max_and_fetch<br/>
|
| 170 |
|
|
__fetch_and_add<br/>
|
| 171 |
|
|
__fetch_and_sub<br/>
|
| 172 |
|
|
__fetch_and_or<br/>
|
| 173 |
|
|
__fetch_and_xor<br/>
|
| 174 |
|
|
__fetch_and_and<br/>
|
| 175 |
|
|
__fetch_and_nand<br/>
|
| 176 |
|
|
__fetch_and_mpy<br/>
|
| 177 |
|
|
__fetch_and_min<br/>
|
| 178 |
|
|
__fetch_and_max<br/>
|
| 179 |
|
|
__lock_test_and_set<br/>
|
| 180 |
|
|
__lock_release<br/>
|
| 181 |
|
|
__lock_acquire<br/>
|
| 182 |
|
|
__compare_and_swap<br/>
|
| 183 |
|
|
__synchronize<br/>
|
| 184 |
|
|
__high_multiply<br/>
|
| 185 |
|
|
__unix<br/>
|
| 186 |
|
|
__sgi<br/>
|
| 187 |
|
|
__linux__<br/>
|
| 188 |
|
|
__i386__<br/>
|
| 189 |
|
|
__i486__<br/>
|
| 190 |
|
|
__cplusplus<br/>
|
| 191 |
|
|
__embedded_cplusplus<br/>
|
| 192 |
|
|
// long double conversion members mangled as __opr<br/>
|
| 193 |
|
|
// http://gcc.gnu.org/ml/libstdc++/1999-q4/msg00060.html<br/>
|
| 194 |
|
|
__opr<br/>
|
| 195 |
|
|
</p></div></div><div class="section" title="By Example"><div class="titlepage"><div><div><h3 class="title"><a id="coding_style.example"/>By Example</h3></div></div></div><div class="literallayout"><p><br/>
|
| 196 |
|
|
This library is written to appropriate C++ coding standards. As such,<br/>
|
| 197 |
|
|
it is intended to precede the recommendations of the GNU Coding<br/>
|
| 198 |
|
|
Standard, which can be referenced in full here:<br/>
|
| 199 |
|
|
<br/>
|
| 200 |
|
|
<a class="link" href="http://www.gnu.org/prep/standards/standards.html#Formatting">http://www.gnu.org/prep/standards/standards.html#Formatting</a><br/>
|
| 201 |
|
|
<br/>
|
| 202 |
|
|
The rest of this is also interesting reading, but skip the "Design<br/>
|
| 203 |
|
|
Advice" part.<br/>
|
| 204 |
|
|
<br/>
|
| 205 |
|
|
The GCC coding conventions are here, and are also useful:<br/>
|
| 206 |
|
|
<a class="link" href="http://gcc.gnu.org/codingconventions.html">http://gcc.gnu.org/codingconventions.html</a><br/>
|
| 207 |
|
|
<br/>
|
| 208 |
|
|
In addition, because it doesn't seem to be stated explicitly anywhere<br/>
|
| 209 |
|
|
else, there is an 80 column source limit.<br/>
|
| 210 |
|
|
<br/>
|
| 211 |
|
|
<code class="filename">ChangeLog</code> entries for member functions should use the<br/>
|
| 212 |
|
|
classname::member function name syntax as follows:<br/>
|
| 213 |
|
|
<br/>
|
| 214 |
|
|
<code class="code"><br/>
|
| 215 |
|
|
1999-04-15 Dennis Ritchie <dr@att.com><br/>
|
| 216 |
|
|
<br/>
|
| 217 |
|
|
* src/basic_file.cc (__basic_file::open): Fix thinko in<br/>
|
| 218 |
|
|
_G_HAVE_IO_FILE_OPEN bits.<br/>
|
| 219 |
|
|
</code><br/>
|
| 220 |
|
|
<br/>
|
| 221 |
|
|
Notable areas of divergence from what may be previous local practice<br/>
|
| 222 |
|
|
(particularly for GNU C) include:<br/>
|
| 223 |
|
|
<br/>
|
| 224 |
|
|
01. Pointers and references<br/>
|
| 225 |
|
|
<code class="code"><br/>
|
| 226 |
|
|
char* p = "flop";<br/>
|
| 227 |
|
|
char& c = *p;<br/>
|
| 228 |
|
|
-NOT-<br/>
|
| 229 |
|
|
char *p = "flop"; // wrong<br/>
|
| 230 |
|
|
char &c = *p; // wrong<br/>
|
| 231 |
|
|
</code><br/>
|
| 232 |
|
|
<br/>
|
| 233 |
|
|
Reason: In C++, definitions are mixed with executable code. Here,<br/>
|
| 234 |
|
|
<code class="code">p</code> is being initialized, not <code class="code">*p</code>. This is near-universal<br/>
|
| 235 |
|
|
practice among C++ programmers; it is normal for C hackers<br/>
|
| 236 |
|
|
to switch spontaneously as they gain experience.<br/>
|
| 237 |
|
|
<br/>
|
| 238 |
|
|
02. Operator names and parentheses<br/>
|
| 239 |
|
|
<code class="code"><br/>
|
| 240 |
|
|
operator==(type)<br/>
|
| 241 |
|
|
-NOT-<br/>
|
| 242 |
|
|
operator == (type) // wrong<br/>
|
| 243 |
|
|
</code><br/>
|
| 244 |
|
|
<br/>
|
| 245 |
|
|
Reason: The <code class="code">==</code> is part of the function name. Separating<br/>
|
| 246 |
|
|
it makes the declaration look like an expression.<br/>
|
| 247 |
|
|
<br/>
|
| 248 |
|
|
03. Function names and parentheses<br/>
|
| 249 |
|
|
<code class="code"><br/>
|
| 250 |
|
|
void mangle()<br/>
|
| 251 |
|
|
-NOT-<br/>
|
| 252 |
|
|
void mangle () // wrong<br/>
|
| 253 |
|
|
</code><br/>
|
| 254 |
|
|
<br/>
|
| 255 |
|
|
Reason: no space before parentheses (except after a control-flow<br/>
|
| 256 |
|
|
keyword) is near-universal practice for C++. It identifies the<br/>
|
| 257 |
|
|
parentheses as the function-call operator or declarator, as<br/>
|
| 258 |
|
|
opposed to an expression or other overloaded use of parentheses.<br/>
|
| 259 |
|
|
<br/>
|
| 260 |
|
|
04. Template function indentation<br/>
|
| 261 |
|
|
<code class="code"><br/>
|
| 262 |
|
|
template<typename T><br/>
|
| 263 |
|
|
void<br/>
|
| 264 |
|
|
template_function(args)<br/>
|
| 265 |
|
|
{ }<br/>
|
| 266 |
|
|
-NOT-<br/>
|
| 267 |
|
|
template<class T><br/>
|
| 268 |
|
|
void template_function(args) {};<br/>
|
| 269 |
|
|
</code><br/>
|
| 270 |
|
|
<br/>
|
| 271 |
|
|
Reason: In class definitions, without indentation whitespace is<br/>
|
| 272 |
|
|
needed both above and below the declaration to distinguish<br/>
|
| 273 |
|
|
it visually from other members. (Also, re: "typename"<br/>
|
| 274 |
|
|
rather than "class".) <code class="code">T</code> often could be <code class="code">int</code>, which is<br/>
|
| 275 |
|
|
not a class. ("class", here, is an anachronism.)<br/>
|
| 276 |
|
|
<br/>
|
| 277 |
|
|
05. Template class indentation<br/>
|
| 278 |
|
|
<code class="code"><br/>
|
| 279 |
|
|
template<typename _CharT, typename _Traits><br/>
|
| 280 |
|
|
class basic_ios : public ios_base<br/>
|
| 281 |
|
|
{<br/>
|
| 282 |
|
|
public:<br/>
|
| 283 |
|
|
// Types:<br/>
|
| 284 |
|
|
};<br/>
|
| 285 |
|
|
-NOT-<br/>
|
| 286 |
|
|
template<class _CharT, class _Traits><br/>
|
| 287 |
|
|
class basic_ios : public ios_base<br/>
|
| 288 |
|
|
{<br/>
|
| 289 |
|
|
public:<br/>
|
| 290 |
|
|
// Types:<br/>
|
| 291 |
|
|
};<br/>
|
| 292 |
|
|
-NOT-<br/>
|
| 293 |
|
|
template<class _CharT, class _Traits><br/>
|
| 294 |
|
|
class basic_ios : public ios_base<br/>
|
| 295 |
|
|
{<br/>
|
| 296 |
|
|
public:<br/>
|
| 297 |
|
|
// Types:<br/>
|
| 298 |
|
|
};<br/>
|
| 299 |
|
|
</code><br/>
|
| 300 |
|
|
<br/>
|
| 301 |
|
|
06. Enumerators<br/>
|
| 302 |
|
|
<code class="code"><br/>
|
| 303 |
|
|
enum<br/>
|
| 304 |
|
|
{<br/>
|
| 305 |
|
|
space = _ISspace,<br/>
|
| 306 |
|
|
print = _ISprint,<br/>
|
| 307 |
|
|
cntrl = _IScntrl<br/>
|
| 308 |
|
|
};<br/>
|
| 309 |
|
|
-NOT-<br/>
|
| 310 |
|
|
enum { space = _ISspace, print = _ISprint, cntrl = _IScntrl };<br/>
|
| 311 |
|
|
</code><br/>
|
| 312 |
|
|
<br/>
|
| 313 |
|
|
07. Member initialization lists<br/>
|
| 314 |
|
|
All one line, separate from class name.<br/>
|
| 315 |
|
|
<br/>
|
| 316 |
|
|
<code class="code"><br/>
|
| 317 |
|
|
gribble::gribble()<br/>
|
| 318 |
|
|
: _M_private_data(0), _M_more_stuff(0), _M_helper(0)<br/>
|
| 319 |
|
|
{ }<br/>
|
| 320 |
|
|
-NOT-<br/>
|
| 321 |
|
|
gribble::gribble() : _M_private_data(0), _M_more_stuff(0), _M_helper(0)<br/>
|
| 322 |
|
|
{ }<br/>
|
| 323 |
|
|
</code><br/>
|
| 324 |
|
|
<br/>
|
| 325 |
|
|
08. Try/Catch blocks<br/>
|
| 326 |
|
|
<code class="code"><br/>
|
| 327 |
|
|
try<br/>
|
| 328 |
|
|
{<br/>
|
| 329 |
|
|
//<br/>
|
| 330 |
|
|
}<br/>
|
| 331 |
|
|
catch (...)<br/>
|
| 332 |
|
|
{<br/>
|
| 333 |
|
|
//<br/>
|
| 334 |
|
|
}<br/>
|
| 335 |
|
|
-NOT-<br/>
|
| 336 |
|
|
try {<br/>
|
| 337 |
|
|
//<br/>
|
| 338 |
|
|
} catch(...) {<br/>
|
| 339 |
|
|
//<br/>
|
| 340 |
|
|
}<br/>
|
| 341 |
|
|
</code><br/>
|
| 342 |
|
|
<br/>
|
| 343 |
|
|
09. Member functions declarations and definitions<br/>
|
| 344 |
|
|
Keywords such as extern, static, export, explicit, inline, etc<br/>
|
| 345 |
|
|
go on the line above the function name. Thus<br/>
|
| 346 |
|
|
<br/>
|
| 347 |
|
|
<code class="code"><br/>
|
| 348 |
|
|
virtual int<br/>
|
| 349 |
|
|
foo()<br/>
|
| 350 |
|
|
-NOT-<br/>
|
| 351 |
|
|
virtual int foo()<br/>
|
| 352 |
|
|
</code><br/>
|
| 353 |
|
|
<br/>
|
| 354 |
|
|
Reason: GNU coding conventions dictate return types for functions<br/>
|
| 355 |
|
|
are on a separate line than the function name and parameter list<br/>
|
| 356 |
|
|
for definitions. For C++, where we have member functions that can<br/>
|
| 357 |
|
|
be either inline definitions or declarations, keeping to this<br/>
|
| 358 |
|
|
standard allows all member function names for a given class to be<br/>
|
| 359 |
|
|
aligned to the same margin, increasing readability.<br/>
|
| 360 |
|
|
<br/>
|
| 361 |
|
|
<br/>
|
| 362 |
|
|
10. Invocation of member functions with "this->"<br/>
|
| 363 |
|
|
For non-uglified names, use <code class="code">this->name</code> to call the function.<br/>
|
| 364 |
|
|
<br/>
|
| 365 |
|
|
<code class="code"><br/>
|
| 366 |
|
|
this->sync()<br/>
|
| 367 |
|
|
-NOT-<br/>
|
| 368 |
|
|
sync()<br/>
|
| 369 |
|
|
</code><br/>
|
| 370 |
|
|
<br/>
|
| 371 |
|
|
Reason: Koenig lookup.<br/>
|
| 372 |
|
|
<br/>
|
| 373 |
|
|
11. Namespaces<br/>
|
| 374 |
|
|
<code class="code"><br/>
|
| 375 |
|
|
namespace std<br/>
|
| 376 |
|
|
{<br/>
|
| 377 |
|
|
blah blah blah;<br/>
|
| 378 |
|
|
} // namespace std<br/>
|
| 379 |
|
|
<br/>
|
| 380 |
|
|
-NOT-<br/>
|
| 381 |
|
|
<br/>
|
| 382 |
|
|
namespace std {<br/>
|
| 383 |
|
|
blah blah blah;<br/>
|
| 384 |
|
|
} // namespace std<br/>
|
| 385 |
|
|
</code><br/>
|
| 386 |
|
|
<br/>
|
| 387 |
|
|
12. Spacing under protected and private in class declarations:<br/>
|
| 388 |
|
|
space above, none below<br/>
|
| 389 |
|
|
i.e.<br/>
|
| 390 |
|
|
<br/>
|
| 391 |
|
|
<code class="code"><br/>
|
| 392 |
|
|
public:<br/>
|
| 393 |
|
|
int foo;<br/>
|
| 394 |
|
|
<br/>
|
| 395 |
|
|
-NOT-<br/>
|
| 396 |
|
|
public:<br/>
|
| 397 |
|
|
<br/>
|
| 398 |
|
|
int foo;<br/>
|
| 399 |
|
|
</code><br/>
|
| 400 |
|
|
<br/>
|
| 401 |
|
|
13. Spacing WRT return statements.<br/>
|
| 402 |
|
|
no extra spacing before returns, no parenthesis<br/>
|
| 403 |
|
|
i.e.<br/>
|
| 404 |
|
|
<br/>
|
| 405 |
|
|
<code class="code"><br/>
|
| 406 |
|
|
}<br/>
|
| 407 |
|
|
return __ret;<br/>
|
| 408 |
|
|
<br/>
|
| 409 |
|
|
-NOT-<br/>
|
| 410 |
|
|
}<br/>
|
| 411 |
|
|
<br/>
|
| 412 |
|
|
return __ret;<br/>
|
| 413 |
|
|
<br/>
|
| 414 |
|
|
-NOT-<br/>
|
| 415 |
|
|
<br/>
|
| 416 |
|
|
}<br/>
|
| 417 |
|
|
return (__ret);<br/>
|
| 418 |
|
|
</code><br/>
|
| 419 |
|
|
<br/>
|
| 420 |
|
|
<br/>
|
| 421 |
|
|
14. Location of global variables.<br/>
|
| 422 |
|
|
All global variables of class type, whether in the "user visible"<br/>
|
| 423 |
|
|
space (e.g., <code class="code">cin</code>) or the implementation namespace, must be defined<br/>
|
| 424 |
|
|
as a character array with the appropriate alignment and then later<br/>
|
| 425 |
|
|
re-initialized to the correct value.<br/>
|
| 426 |
|
|
<br/>
|
| 427 |
|
|
This is due to startup issues on certain platforms, such as AIX.<br/>
|
| 428 |
|
|
For more explanation and examples, see <code class="filename">src/globals.cc</code>. All such<br/>
|
| 429 |
|
|
variables should be contained in that file, for simplicity.<br/>
|
| 430 |
|
|
<br/>
|
| 431 |
|
|
15. Exception abstractions<br/>
|
| 432 |
|
|
Use the exception abstractions found in <code class="filename">functexcept.h</code>, which allow<br/>
|
| 433 |
|
|
C++ programmers to use this library with <code class="literal">-fno-exceptions</code>. (Even if<br/>
|
| 434 |
|
|
that is rarely advisable, it's a necessary evil for backwards<br/>
|
| 435 |
|
|
compatibility.)<br/>
|
| 436 |
|
|
<br/>
|
| 437 |
|
|
16. Exception error messages<br/>
|
| 438 |
|
|
All start with the name of the function where the exception is<br/>
|
| 439 |
|
|
thrown, and then (optional) descriptive text is added. Example:<br/>
|
| 440 |
|
|
<br/>
|
| 441 |
|
|
<code class="code"><br/>
|
| 442 |
|
|
__throw_logic_error(__N("basic_string::_S_construct NULL not valid"));<br/>
|
| 443 |
|
|
</code><br/>
|
| 444 |
|
|
<br/>
|
| 445 |
|
|
Reason: The verbose terminate handler prints out <code class="code">exception::what()</code>,<br/>
|
| 446 |
|
|
as well as the typeinfo for the thrown exception. As this is the<br/>
|
| 447 |
|
|
default terminate handler, by putting location info into the<br/>
|
| 448 |
|
|
exception string, a very useful error message is printed out for<br/>
|
| 449 |
|
|
uncaught exceptions. So useful, in fact, that non-programmers can<br/>
|
| 450 |
|
|
give useful error messages, and programmers can intelligently<br/>
|
| 451 |
|
|
speculate what went wrong without even using a debugger.<br/>
|
| 452 |
|
|
<br/>
|
| 453 |
|
|
17. The doxygen style guide to comments is a separate document,<br/>
|
| 454 |
|
|
see index.<br/>
|
| 455 |
|
|
<br/>
|
| 456 |
|
|
The library currently has a mixture of GNU-C and modern C++ coding<br/>
|
| 457 |
|
|
styles. The GNU C usages will be combed out gradually.<br/>
|
| 458 |
|
|
<br/>
|
| 459 |
|
|
Name patterns:<br/>
|
| 460 |
|
|
<br/>
|
| 461 |
|
|
For nonstandard names appearing in Standard headers, we are constrained<br/>
|
| 462 |
|
|
to use names that begin with underscores. This is called "uglification".<br/>
|
| 463 |
|
|
The convention is:<br/>
|
| 464 |
|
|
<br/>
|
| 465 |
|
|
Local and argument names: <code class="literal">__[a-z].*</code><br/>
|
| 466 |
|
|
<br/>
|
| 467 |
|
|
Examples: <code class="code">__count __ix __s1</code><br/>
|
| 468 |
|
|
<br/>
|
| 469 |
|
|
Type names and template formal-argument names: <code class="literal">_[A-Z][^_].*</code><br/>
|
| 470 |
|
|
<br/>
|
| 471 |
|
|
Examples: <code class="code">_Helper _CharT _N</code><br/>
|
| 472 |
|
|
<br/>
|
| 473 |
|
|
Member data and function names: <code class="literal">_M_.*</code><br/>
|
| 474 |
|
|
<br/>
|
| 475 |
|
|
Examples: <code class="code">_M_num_elements _M_initialize ()</code><br/>
|
| 476 |
|
|
<br/>
|
| 477 |
|
|
Static data members, constants, and enumerations: <code class="literal">_S_.*</code><br/>
|
| 478 |
|
|
<br/>
|
| 479 |
|
|
Examples: <code class="code">_S_max_elements _S_default_value</code><br/>
|
| 480 |
|
|
<br/>
|
| 481 |
|
|
Don't use names in the same scope that differ only in the prefix,<br/>
|
| 482 |
|
|
e.g. _S_top and _M_top. See BADNAMES for a list of forbidden names.<br/>
|
| 483 |
|
|
(The most tempting of these seem to be and "_T" and "__sz".)<br/>
|
| 484 |
|
|
<br/>
|
| 485 |
|
|
Names must never have "__" internally; it would confuse name<br/>
|
| 486 |
|
|
unmanglers on some targets. Also, never use "__[0-9]", same reason.<br/>
|
| 487 |
|
|
<br/>
|
| 488 |
|
|
--------------------------<br/>
|
| 489 |
|
|
<br/>
|
| 490 |
|
|
[BY EXAMPLE]<br/>
|
| 491 |
|
|
<code class="code"><br/>
|
| 492 |
|
|
<br/>
|
| 493 |
|
|
#ifndef _HEADER_<br/>
|
| 494 |
|
|
#define _HEADER_ 1<br/>
|
| 495 |
|
|
<br/>
|
| 496 |
|
|
namespace std<br/>
|
| 497 |
|
|
{<br/>
|
| 498 |
|
|
class gribble<br/>
|
| 499 |
|
|
{<br/>
|
| 500 |
|
|
public:<br/>
|
| 501 |
|
|
gribble() throw();<br/>
|
| 502 |
|
|
<br/>
|
| 503 |
|
|
gribble(const gribble&);<br/>
|
| 504 |
|
|
<br/>
|
| 505 |
|
|
explicit<br/>
|
| 506 |
|
|
gribble(int __howmany);<br/>
|
| 507 |
|
|
<br/>
|
| 508 |
|
|
gribble&<br/>
|
| 509 |
|
|
operator=(const gribble&);<br/>
|
| 510 |
|
|
<br/>
|
| 511 |
|
|
virtual<br/>
|
| 512 |
|
|
~gribble() throw ();<br/>
|
| 513 |
|
|
<br/>
|
| 514 |
|
|
// Start with a capital letter, end with a period.<br/>
|
| 515 |
|
|
inline void<br/>
|
| 516 |
|
|
public_member(const char* __arg) const;<br/>
|
| 517 |
|
|
<br/>
|
| 518 |
|
|
// In-class function definitions should be restricted to one-liners.<br/>
|
| 519 |
|
|
int<br/>
|
| 520 |
|
|
one_line() { return 0 }<br/>
|
| 521 |
|
|
<br/>
|
| 522 |
|
|
int<br/>
|
| 523 |
|
|
two_lines(const char* arg)<br/>
|
| 524 |
|
|
{ return strchr(arg, 'a'); }<br/>
|
| 525 |
|
|
<br/>
|
| 526 |
|
|
inline int<br/>
|
| 527 |
|
|
three_lines(); // inline, but defined below.<br/>
|
| 528 |
|
|
<br/>
|
| 529 |
|
|
// Note indentation.<br/>
|
| 530 |
|
|
template<typename _Formal_argument><br/>
|
| 531 |
|
|
void<br/>
|
| 532 |
|
|
public_template() const throw();<br/>
|
| 533 |
|
|
<br/>
|
| 534 |
|
|
template<typename _Iterator><br/>
|
| 535 |
|
|
void<br/>
|
| 536 |
|
|
other_template();<br/>
|
| 537 |
|
|
<br/>
|
| 538 |
|
|
private:<br/>
|
| 539 |
|
|
class _Helper;<br/>
|
| 540 |
|
|
<br/>
|
| 541 |
|
|
int _M_private_data;<br/>
|
| 542 |
|
|
int _M_more_stuff;<br/>
|
| 543 |
|
|
_Helper* _M_helper;<br/>
|
| 544 |
|
|
int _M_private_function();<br/>
|
| 545 |
|
|
<br/>
|
| 546 |
|
|
enum _Enum<br/>
|
| 547 |
|
|
{<br/>
|
| 548 |
|
|
_S_one,<br/>
|
| 549 |
|
|
_S_two<br/>
|
| 550 |
|
|
};<br/>
|
| 551 |
|
|
<br/>
|
| 552 |
|
|
static void<br/>
|
| 553 |
|
|
_S_initialize_library();<br/>
|
| 554 |
|
|
};<br/>
|
| 555 |
|
|
<br/>
|
| 556 |
|
|
// More-or-less-standard language features described by lack, not presence.<br/>
|
| 557 |
|
|
# ifndef _G_NO_LONGLONG<br/>
|
| 558 |
|
|
extern long long _G_global_with_a_good_long_name; // avoid globals!<br/>
|
| 559 |
|
|
# endif<br/>
|
| 560 |
|
|
<br/>
|
| 561 |
|
|
// Avoid in-class inline definitions, define separately;<br/>
|
| 562 |
|
|
// likewise for member class definitions:<br/>
|
| 563 |
|
|
inline int<br/>
|
| 564 |
|
|
gribble::public_member() const<br/>
|
| 565 |
|
|
{ int __local = 0; return __local; }<br/>
|
| 566 |
|
|
<br/>
|
| 567 |
|
|
class gribble::_Helper<br/>
|
| 568 |
|
|
{<br/>
|
| 569 |
|
|
int _M_stuff;<br/>
|
| 570 |
|
|
<br/>
|
| 571 |
|
|
friend class gribble;<br/>
|
| 572 |
|
|
};<br/>
|
| 573 |
|
|
}<br/>
|
| 574 |
|
|
<br/>
|
| 575 |
|
|
// Names beginning with "__": only for arguments and<br/>
|
| 576 |
|
|
// local variables; never use "__" in a type name, or<br/>
|
| 577 |
|
|
// within any name; never use "__[0-9]".<br/>
|
| 578 |
|
|
<br/>
|
| 579 |
|
|
#endif /* _HEADER_ */<br/>
|
| 580 |
|
|
<br/>
|
| 581 |
|
|
<br/>
|
| 582 |
|
|
namespace std<br/>
|
| 583 |
|
|
{<br/>
|
| 584 |
|
|
template<typename T> // notice: "typename", not "class", no space<br/>
|
| 585 |
|
|
long_return_value_type<with_many, args><br/>
|
| 586 |
|
|
function_name(char* pointer, // "char *pointer" is wrong.<br/>
|
| 587 |
|
|
char* argument,<br/>
|
| 588 |
|
|
const Reference& ref)<br/>
|
| 589 |
|
|
{<br/>
|
| 590 |
|
|
// int a_local; /* wrong; see below. */<br/>
|
| 591 |
|
|
if (test)<br/>
|
| 592 |
|
|
{<br/>
|
| 593 |
|
|
nested code<br/>
|
| 594 |
|
|
}<br/>
|
| 595 |
|
|
<br/>
|
| 596 |
|
|
int a_local = 0; // declare variable at first use.<br/>
|
| 597 |
|
|
<br/>
|
| 598 |
|
|
// char a, b, *p; /* wrong */<br/>
|
| 599 |
|
|
char a = 'a';<br/>
|
| 600 |
|
|
char b = a + 1;<br/>
|
| 601 |
|
|
char* c = "abc"; // each variable goes on its own line, always.<br/>
|
| 602 |
|
|
<br/>
|
| 603 |
|
|
// except maybe here...<br/>
|
| 604 |
|
|
for (unsigned i = 0, mask = 1; mask; ++i, mask <<= 1) {<br/>
|
| 605 |
|
|
// ...<br/>
|
| 606 |
|
|
}<br/>
|
| 607 |
|
|
}<br/>
|
| 608 |
|
|
<br/>
|
| 609 |
|
|
gribble::gribble()<br/>
|
| 610 |
|
|
: _M_private_data(0), _M_more_stuff(0), _M_helper(0)<br/>
|
| 611 |
|
|
{ }<br/>
|
| 612 |
|
|
<br/>
|
| 613 |
|
|
int<br/>
|
| 614 |
|
|
gribble::three_lines()<br/>
|
| 615 |
|
|
{<br/>
|
| 616 |
|
|
// doesn't fit in one line.<br/>
|
| 617 |
|
|
}<br/>
|
| 618 |
|
|
} // namespace std<br/>
|
| 619 |
|
|
</code><br/>
|
| 620 |
|
|
</p></div></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="source_organization.html">Prev</a> </td><td align="center"><a accesskey="u" href="appendix_contributing.html">Up</a></td><td align="right"> <a accesskey="n" href="source_design_notes.html">Next</a></td></tr><tr><td align="left" valign="top">Directory Layout and Source Conventions </td><td align="center"><a accesskey="h" href="../index.html">Home</a></td><td align="right" valign="top"> Design Notes</td></tr></table></div></body></html>
|
