libstdc++-v3/doc/html/manual/source_code_style.html

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