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

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