1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!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/html; charset=UTF-8" /><title>Coding Style</title><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><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 width="20%" align="left"><a accesskey="p" href="source_organization.html">Prev</a> </td><th width="60%" align="center">Appendix A. 3 Contributing 4 5</th><td width="20%" align="right"> <a accesskey="n" href="source_design_notes.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="contrib.coding_style"></a>Coding Style</h2></div></div></div><p> 6 </p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="coding_style.bad_identifiers"></a>Bad Identifiers</h3></div></div></div><p> 7 Identifiers that conflict and should be avoided. 8 </p><div class="literallayout"><p><br /> 9 This is the list of names <span class="quote">“<span class="quote">reserved to the<br /> 10 implementation</span>”</span> that have been claimed by certain<br /> 11 compilers and system headers of interest, and should not be used<br /> 12 in the library. It will grow, of course. We generally are<br /> 13 interested in names that are not all-caps, except for those like<br /> 14 "_T"<br /> 15<br /> 16 For Solaris:<br /> 17 _B<br /> 18 _C<br /> 19 _L<br /> 20 _N<br /> 21 _P<br /> 22 _S<br /> 23 _U<br /> 24 _X<br /> 25 _E1<br /> 26 ..<br /> 27 _E24<br /> 28<br /> 29 Irix adds:<br /> 30 _A<br /> 31 _G<br /> 32<br /> 33 MS adds:<br /> 34 _T<br /> 35 __deref<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 VxWorks adds:<br /> 53 _C2<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"><div class="titlepage"><div><div><h3 class="title"><a id="coding_style.example"></a>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" target="_top">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" target="_top">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 /> 2151999-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 <a class="link" href="source_code_style.html#coding_style.bad_identifiers" title="Bad Identifiers">BADNAMES</a> 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 width="40%" align="left"><a accesskey="p" href="source_organization.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendix_contributing.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="source_design_notes.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Directory Layout and Source Conventions </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Design Notes</td></tr></table></div></body></html>