docs/CodingStandards.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
   2                       "http://www.w3.org/TR/html4/strict.dtd">
   3 <html>
   4 <head>
   5   <link rel="stylesheet" href="llvm.css" type="text/css">
   6   <title>A Few Coding Standards</title>
   7 </head>
   8 <body>
   9
  10 <div class="doc_title">
  11   A Few Coding Standards
  12 </div>
  13
  14 <ol>
  15   <li><a href="#introduction">Introduction</a></li>
  16   <li><a href="#mechanicalissues">Mechanical Source Issues</a>
  17     <ol>
  18       <li><a href="#sourceformating">Source Code Formatting</a>
  19         <ol>
  20           <li><a href="#scf_commenting">Commenting</a></li>
  21           <li><a href="#scf_commentformat">Comment Formatting</a></li>
  22           <li><a href="#scf_includes"><tt>#include</tt> Style</a></li>
  23           <li><a href="#scf_codewidth">Source Code Width</a></li>
  24           <li><a href="#scf_spacestabs">Use Spaces Instead of Tabs</a></li>
  25           <li><a href="#scf_indentation">Indent Code Consistently</a></li>
  26         </ol></li>
  27       <li><a href="#compilerissues">Compiler Issues</a>
  28         <ol>
  29           <li><a href="#ci_warningerrors">Treat Compiler Warnings Like
  30               Errors</a></li>
  31           <li><a href="#ci_portable_code">Write Portable Code</a></li>
  32           <li><a href="#ci_class_struct">Use of class/struct Keywords</a></li>
  33         </ol></li>
  34     </ol></li>
  35   <li><a href="#styleissues">Style Issues</a>
  36     <ol>
  37       <li><a href="#macro">The High Level Issues</a>
  38         <ol>
  39           <li><a href="#hl_module">A Public Header File <b>is</b> a
  40               Module</a></li>
  41           <li><a href="#hl_dontinclude">#include as Little as Possible</a></li>
  42           <li><a href="#hl_privateheaders">Keep "internal" Headers
  43               Private</a></li>
  44         </ol></li>
  45       <li><a href="#micro">The Low Level Issues</a>
  46         <ol>
  47           <li><a href="#ll_assert">Assert Liberally</a></li>
  48           <li><a href="#ll_ns_std">Do not use 'using namespace std'</a></li>
  49           <li><a href="#ll_virtual_anch">Provide a virtual method anchor for clases in headers</a></li>
  50           <li><a href="#ll_preincrement">Prefer Preincrement</a></li>
  51           <li><a href="#ll_avoidendl">Avoid <tt>std::endl</tt></a></li>
  52         </ol></li>
  53     </ol></li>
  54   <li><a href="#seealso">See Also</a></li>
  55 </ol>
  56
  57 <div class="doc_author">
  58   <p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a></p>
  59 </div>
  60
  61
  62 <!-- *********************************************************************** -->
  63 <div class="doc_section">
  64   <a name="introduction">Introduction</a>
  65 </div>
  66 <!-- *********************************************************************** -->
  67
  68 <div class="doc_text">
  69
  70 <p>This document attempts to describe a few coding standards that are being used
  71 in the LLVM source tree.  Although no coding standards should be regarded as
  72 absolute requirements to be followed in all instances, coding standards can be
  73 useful.</p>
  74
  75 <p>This document intentionally does not prescribe fixed standards for religious
  76 issues such as brace placement and space usage.  For issues like this, follow
  77 the golden rule:</p>
  78
  79 <blockquote>
  80
  81 <p><b><a name="goldenrule">If you are adding a significant body of source to a
  82 project, feel free to use whatever style you are most comfortable with.  If you
  83 are extending, enhancing, or bug fixing already implemented code, use the style
  84 that is already being used so that the source is uniform and easy to
  85 follow.</a></b></p>
  86
  87 </blockquote>
  88
  89 <p>The ultimate goal of these guidelines is the increase readability and
  90 maintainability of our common source base. If you have suggestions for topics to
  91 be included, please mail them to <a
  92 href="mailto:sabre@nondot.org">Chris</a>.</p>
  93
  94 </div>
  95
  96 <!-- *********************************************************************** -->
  97 <div class="doc_section">
  98   <a name="mechanicalissues">Mechanical Source Issues</a>
  99 </div>
 100 <!-- *********************************************************************** -->
 101
 102 <!-- ======================================================================= -->
 103 <div class="doc_subsection">
 104   <a name="sourceformating">Source Code Formatting</a>
 105 </div>
 106
 107 <!-- _______________________________________________________________________ -->
 108 <div class="doc_subsubsection">
 109   <a name="scf_commenting">Commenting</a>
 110 </div>
 111
 112 <div class="doc_text">
 113
 114 <p>Comments are one critical part of readability and maintainability.  Everyone
 115 knows they should comment, so should you.  Although we all should probably
 116 comment our code more than we do, there are a few very critical places that
 117 documentation is very useful:</p>
 118
 119 <b>File Headers</b>
 120
 121 <p>Every source file should have a header on it that
 122 describes the basic purpose of the file.  If a file does not have a header, it
 123 should not be checked into CVS.  Most source trees will probably have a standard
 124 file header format.  The standard format for the LLVM source tree looks like
 125 this:</p>
 126
 127 <div class="doc_code">
 128 <pre>
 129 //===-- llvm/Instruction.h - Instruction class definition -------*- C++ -*-===//
 130 //
 131 //                     The LLVM Compiler Infrastructure
 132 //
 133 // This file was developed by the LLVM research group and is distributed under
 134 // the University of Illinois Open Source License. See LICENSE.TXT for details.
 135 //
 136 //===----------------------------------------------------------------------===//
 137 //
 138 // This file contains the declaration of the Instruction class, which is the
 139 // base class for all of the VM instructions.
 140 //
 141 //===----------------------------------------------------------------------===//
 142 </pre>
 143 </div>
 144
 145 <p>A few things to note about this particular format:  The "<tt>-*- C++
 146 -*-</tt>" string on the first line is there to tell Emacs that the source file
 147 is a C++ file, not a C file (Emacs assumes .h files are C files by default).
 148 Note that this tag is not necessary in .cpp files.  The name of the file is also
 149 on the first line, along with a very short description of the purpose of the
 150 file.  This is important when printing out code and flipping though lots of
 151 pages.</p>
 152
 153 <p>The next section in the file is a concise note that defines the license that
 154 the file is released under.  This makes it perfectly clear what terms the source
 155 code can be distributed under.</p>
 156
 157 <p>The main body of the description does not have to be very long in most cases.
 158 Here it's only two lines.  If an algorithm is being implemented or something
 159 tricky is going on, a reference to the paper where it is published should be
 160 included, as well as any notes or "gotchas" in the code to watch out for.</p>
 161
 162 <b>Class overviews</b>
 163
 164 <p>Classes are one fundamental part of a good object oriented design.  As such,
 165 a class definition should have a comment block that explains what the class is
 166 used for... if it's not obvious.  If it's so completely obvious your grandma
 167 could figure it out, it's probably safe to leave it out.  Naming classes
 168 something sane goes a long ways towards avoiding writing documentation.</p>
 169
 170
 171 <b>Method information</b>
 172
 173 <p>Methods defined in a class (as well as any global functions) should also be
 174 documented properly.  A quick note about what it does any a description of the
 175 borderline behaviour is all that is necessary here (unless something
 176 particularly tricky or insideous is going on).  The hope is that people can
 177 figure out how to use your interfaces without reading the code itself... that is
 178 the goal metric.</p>
 179
 180 <p>Good things to talk about here are what happens when something unexpected
 181 happens: does the method return null?  Abort?  Format your hard disk?</p>
 182
 183 </div>
 184
 185 <!-- _______________________________________________________________________ -->
 186 <div class="doc_subsubsection">
 187   <a name="scf_commentformat">Comment Formatting</a>
 188 </div>
 189
 190 <div class="doc_text">
 191
 192 <p>In general, prefer C++ style (<tt>//</tt>) comments.  They take less space,
 193 require less typing, don't have nesting problems, etc.  There are a few cases
 194 when it is useful to use C style (<tt>/* */</tt>) comments however:</p>
 195
 196 <ol>
 197   <li>When writing a C code: Obviously if you are writing C code, use C style
 198       comments.</li>
 199   <li>When writing a header file that may be <tt>#include</tt>d by a C source
 200       file.</li>
 201   <li>When writing a source file that is used by a tool that only accepts C
 202       style comments.</li>
 203 </ol>
 204
 205 <p>To comment out a large block of code, use <tt>#if 0</tt> and <tt>#endif</tt>.
 206 These nest properly and are better behaved in general than C style comments.</p>
 207
 208 </div>
 209
 210 <!-- _______________________________________________________________________ -->
 211 <div class="doc_subsubsection">
 212   <a name="scf_includes"><tt>#include</tt> Style</a>
 213 </div>
 214
 215 <div class="doc_text">
 216
 217 <p>Immediately after the <a href="#scf_commenting">header file comment</a> (and
 218 include guards if working on a header file), the <a
 219 href="#hl_dontinclude">minimal</a> list of <tt>#include</tt>s required by the
 220 file should be listed.  We prefer these <tt>#include</tt>s to be listed in this
 221 order:</p>
 222
 223 <ol>
 224   <li><a href="#mmheader">Main Module header</a></li>
 225   <li><a href="#hl_privateheaders">Local/Private Headers</a></li>
 226   <li><tt>llvm/*</tt></li>
 227   <li><tt>llvm/Analysis/*</tt></li>
 228   <li><tt>llvm/Assembly/*</tt></li>
 229   <li><tt>llvm/Bytecode/*</tt></li>
 230   <li><tt>llvm/CodeGen/*</tt></li>
 231   <li>...</li>
 232   <li><tt>Support/*</tt></li>
 233   <li><tt>Config/*</tt></li>
 234   <li>System <tt>#includes</tt></li>
 235 </ol>
 236
 237 <p>... and each catagory should be sorted by name.</p>
 238
 239 <p><a name="mmheader">The "Main Module Header"</a> file applies to .cpp file
 240 which implement an interface defined by a .h file.  This <tt>#include</tt>
 241 should always be included <b>first</b> regardless of where it lives on the file
 242 system.  By including a header file first in the .cpp files that implement the
 243 interfaces, we ensure that the header does not have any hidden dependencies
 244 which are not explicitly #included in the header, but should be.  It is also a
 245 form of documentation in the .cpp file to indicate where the interfaces it
 246 implements are defined.</p>
 247
 248 </div>
 249
 250 <!-- _______________________________________________________________________ -->
 251 <div class="doc_subsubsection">
 252   <a name="scf_codewidth">Source Code Width</a>
 253 </div>
 254
 255 <div class="doc_text">
 256
 257 <p>Write your code to fit within 80 columns of text.  This helps those of us who
 258 like to print out code and look at your code in an xterm without resizing
 259 it.</p>
 260
 261 </div>
 262
 263 <!-- _______________________________________________________________________ -->
 264 <div class="doc_subsubsection">
 265   <a name="scf_spacestabs">Use Spaces Instead of Tabs</a>
 266 </div>
 267
 268 <div class="doc_text">
 269
 270 <p>In all cases, prefer spaces to tabs in source files.  People have different
 271 prefered indentation levels, and different styles of indentation that they
 272 like... this is fine.  What isn't is that different editors/viewers expand tabs
 273 out to different tab stops.  This can cause your code to look completely
 274 unreadable, and it is not worth dealing with.</p>
 275
 276 <p>As always, follow the <a href="#goldenrule">Golden Rule</a> above: follow the
 277 style of existing code if your are modifying and extending it.  If you like four
 278 spaces of indentation, <b>DO NOT</b> do that in the middle of a chunk of code
 279 with two spaces of indentation.  Also, do not reindent a whole source file: it
 280 makes for incredible diffs that are absolutely worthless.</p>
 281
 282 </div>
 283
 284 <!-- _______________________________________________________________________ -->
 285 <div class="doc_subsubsection">
 286   <a name="scf_indentation">Indent Code Consistently</a>
 287 </div>
 288
 289 <div class="doc_text">
 290
 291 <p>Okay, your first year of programming you were told that indentation is
 292 important.  If you didn't believe and internalize this then, now is the time.
 293 Just do it.</p>
 294
 295 </div>
 296
 297
 298 <!-- ======================================================================= -->
 299 <div class="doc_subsection">
 300   <a name="compilerissues">Compiler Issues</a>
 301 </div>
 302
 303
 304 <!-- _______________________________________________________________________ -->
 305 <div class="doc_subsubsection">
 306   <a name="ci_warningerrors">Treat Compiler Warnings Like Errors</a>
 307 </div>
 308
 309 <div class="doc_text">
 310
 311 <p>If your code has compiler warnings in it, something is wrong: you aren't
 312 casting values correctly, your have "questionable" constructs in your code, or
 313 you are doing something legitimately wrong.  Compiler warnings can cover up
 314 legitimate errors in output and make dealing with a translation unit
 315 difficult.</p>
 316
 317 <p>It is not possible to prevent all warnings from all compilers, nor is it
 318 desirable.  Instead, pick a standard compiler (like <tt>gcc</tt>) that provides
 319 a good thorough set of warnings, and stick to them.  At least in the case of
 320 <tt>gcc</tt>, it is possible to work around any spurious errors by changing the
 321 syntax of the code slightly.  For example, an warning that annoys me occurs when
 322 I write code like this:</p>
 323
 324 <div class="doc_code">
 325 <pre>
 326 if (V = getValue()) {
 327   ...
 328 }
 329 </pre>
 330 </div>
 331
 332 <p><tt>gcc</tt> will warn me that I probably want to use the <tt>==</tt>
 333 operator, and that I probably mistyped it.  In most cases, I haven't, and I
 334 really don't want the spurious errors.  To fix this particular problem, I
 335 rewrite the code like this:</p>
 336
 337 <div class="doc_code">
 338 <pre>
 339 if ((V = getValue())) {
 340   ...
 341 }
 342 </pre>
 343 </div>
 344
 345 <p>...which shuts <tt>gcc</tt> up.  Any <tt>gcc</tt> warning that annoys you can
 346 be fixed by massaging the code appropriately.</p>
 347
 348 <p>These are the <tt>gcc</tt> warnings that I prefer to enable: <tt>-Wall
 349 -Winline -W -Wwrite-strings -Wno-unused</tt></p>
 350
 351 </div>
 352
 353 <!-- _______________________________________________________________________ -->
 354 <div class="doc_subsubsection">
 355   <a name="ci_portable_code">Write Portable Code</a>
 356 </div>
 357
 358 <div class="doc_text">
 359
 360 <p>In almost all cases, it is possible and within reason to write completely
 361 portable code.  If there are cases where it isn't possible to write portable
 362 code, isolate it behind a well defined (and well documented) interface.</p>
 363
 364 <p>In practice, this means that you shouldn't assume much about the host
 365 compiler, including its support for "high tech" features like partial
 366 specialization of templates.  In fact, Visual C++ 6 could be an important target
 367 for our work in the future, and we don't want to have to rewrite all of our code
 368 to support it.</p>
 369
 370 </div>
 371
 372 <!-- _______________________________________________________________________ -->
 373 <div class="doc_subsubsection">
 374 <a name="ci_class_struct">Use of <tt>class</tt> and <tt>struct</tt> Keywords</a>
 375 </div>
 376 <div class="doc_text">
 377
 378 <p>In C++, the <tt>class</tt> and <tt>struct</tt> keywords can be used almost
 379 interchangeably. The only difference is when they are used to declare a class:
 380 <tt>class</tt> makes all members private by default while <tt>struct</tt> makes
 381 all members public by default.</p>
 382
 383 <p>Unfortunately, not all compilers follow the rules and some will generate
 384 different symbols based on whether <tt>class</tt> or <tt>struct</tt> was used to
 385 declare the symbol.  This can lead to problems at link time.</p>
 386
 387 <p>So, the rule for LLVM is to always use the <tt>class</tt> keyword, unless
 388 <b>all</b> members are public, in which case <tt>struct</tt> is allowed.</p>
 389
 390 </div>
 391
 392 <!-- *********************************************************************** -->
 393 <div class="doc_section">
 394   <a name="styleissues">Style Issues</a>
 395 </div>
 396 <!-- *********************************************************************** -->
 397
 398
 399 <!-- ======================================================================= -->
 400 <div class="doc_subsection">
 401   <a name="macro">The High Level Issues</a>
 402 </div>
 403
 404
 405 <!-- _______________________________________________________________________ -->
 406 <div class="doc_subsubsection">
 407   <a name="hl_module">A Public Header File <b>is</b> a Module</a>
 408 </div>
 409
 410 <div class="doc_text">
 411
 412 <p>C++ doesn't do too well in the modularity department.  There is no real
 413 encapsulation or data hiding (unless you use expensive protocol classes), but it
 414 is what we have to work with.  When you write a public header file (in the LLVM
 415 source tree, they live in the top level "include" directory), you are defining a
 416 module of functionality.</p>
 417
 418 <p>Ideally, modules should be completely independent of each other, and their
 419 header files should only include the absolute minimum number of headers
 420 possible. A module is not just a class, a function, or a namespace: <a
 421 href="http://www.cuj.com/articles/2000/0002/0002c/0002c.htm">it's a collection
 422 of these</a> that defines an interface.  This interface may be several
 423 functions, classes or data structures, but the important issue is how they work
 424 together.</p>
 425
 426 <p>In general, a module should be implemented with one or more <tt>.cpp</tt>
 427 files.  Each of these <tt>.cpp</tt> files should include the header that defines
 428 their interface first.  This ensure that all of the dependences of the module
 429 header have been properly added to the module header itself, and are not
 430 implicit.  System headers should be included after user headers for a
 431 translation unit.</p>
 432
 433 </div>
 434
 435 <!-- _______________________________________________________________________ -->
 436 <div class="doc_subsubsection">
 437   <a name="hl_dontinclude"><tt>#include</tt> as Little as Possible</a>
 438 </div>
 439
 440 <div class="doc_text">
 441
 442 <p><tt>#include</tt> hurts compile time performance.  Don't do it unless you
 443 have to, especially in header files.</p>
 444
 445 <p>But wait, sometimes you need to have the definition of a class to use it, or
 446 to inherit from it.  In these cases go ahead and <tt>#include</tt> that header
 447 file.  Be aware however that there are many cases where you don't need to have
 448 the full definition of a class.  If you are using a pointer or reference to a
 449 class, you don't need the header file.  If you are simply returning a class
 450 instance from a prototyped function or method, you don't need it.  In fact, for
 451 most cases, you simply don't need the definition of a class... and not
 452 <tt>#include</tt>'ing speeds up compilation.</p>
 453
 454 <p>It is easy to try to go too overboard on this recommendation, however.  You
 455 <b>must</b> include all of the header files that you are using, either directly
 456 or indirectly (through another header file).  To make sure that you don't
 457 accidently forget to include a header file in your module header, make sure to
 458 include your module header <b>first</b> in the implementation file (as mentioned
 459 above).  This way there won't be any hidden dependencies that you'll find out
 460 about later...</p>
 461
 462 </div>
 463
 464 <!-- _______________________________________________________________________ -->
 465 <div class="doc_subsubsection">
 466   <a name="hl_privateheaders">Keep "internal" Headers Private</a>
 467 </div>
 468
 469 <div class="doc_text">
 470
 471 <p>Many modules have a complex implementation that causes them to use more than
 472 one implementation (<tt>.cpp</tt>) file.  It is often tempting to put the
 473 internal communication interface (helper classes, extra functions, etc) in the
 474 public module header file.  Don't do this.</p>
 475
 476 <p>If you really need to do something like this, put a private header file in
 477 the same directory as the source files, and include it locally.  This ensures
 478 that your private interface remains private and undisturbed by outsiders.</p>
 479
 480 <p>Note however, that it's okay to put extra implementation methods a public
 481 class itself... just make them private (or protected), and all is well.</p>
 482
 483 </div>
 484
 485 <!-- ======================================================================= -->
 486 <div class="doc_subsection">
 487   <a name="micro">The Low Level Issues</a>
 488 </div>
 489
 490
 491 <!-- _______________________________________________________________________ -->
 492 <div class="doc_subsubsection">
 493   <a name="ll_assert">Assert Liberally</a>
 494 </div>
 495
 496 <div class="doc_text">
 497
 498 <p>Use the "<tt>assert</tt>" function to its fullest.  Check all of your
 499 preconditions and assumptions, you never know when a bug (not neccesarily even
 500 yours) might be caught early by an assertion, which reduces debugging time
 501 dramatically.  The "<tt>&lt;cassert&gt;</tt>" header file is probably already
 502 included by the header files you are using, so it doesn't cost anything to use
 503 it.</p>
 504
 505 <p>To further assist with debugging, make sure to put some kind of error message
 506 in the assertion statement (which is printed if the assertion is tripped). This
 507 helps the poor debugging make sense of why an assertion is being made and
 508 enforced, and hopefully what to do about it.  Here is one complete example:</p>
 509
 510 <div class="doc_code">
 511 <pre>
 512 inline Value *getOperand(unsigned i) {
 513   assert(i &lt; Operands.size() &amp;&amp; "getOperand() out of range!");
 514   return Operands[i];
 515 }
 516 </pre>
 517 </div>
 518
 519 <p>Here are some examples:</p>
 520
 521 <div class="doc_code">
 522 <pre>
 523 assert(Ty-&gt;isPointerType() &amp;&amp; "Can't allocate a non pointer type!");
 524
 525 assert((Opcode == Shl || Opcode == Shr) &amp;&amp; "ShiftInst Opcode invalid!");
 526
 527 assert(idx &lt; getNumSuccessors() &amp;&amp; "Successor # out of range!");
 528
 529 assert(V1.getType() == V2.getType() &amp;&amp; "Constant types must be identical!");
 530
 531 assert(isa&lt;PHINode&gt;(Succ-&gt;front()) &amp;&amp; "Only works on PHId BBs!");
 532 </pre>
 533 </div>
 534
 535 <p>You get the idea...</p>
 536
 537 </div>
 538
 539 <!-- _______________________________________________________________________ -->
 540 <div class="doc_subsubsection">
 541   <a name="ll_ns_std">Do not use 'using namespace std'</a>
 542 </div>
 543
 544 <div class="doc_text">
 545 <p>In LLVM, we prefer to explicitly prefix all identifiers from the standard
 546 namespace with an "std::" prefix, rather than rely on "using namespace std;".
 547 </p>
 548
 549 <p> In header files, adding a 'using namespace XXX' directive pollutes the
 550 namespace of any source file that includes the header.  This is clearly a bad
 551 thing.</p>
 552
 553 <p>In implementation files (e.g. .cpp files) the rule is more of a stylistic
 554 rule, but is still important.  Basically, using explicit namespace prefixes
 555 makes
 556 the code <b>more clear</b> - because it is immediately obvious what facilities
 557 are being used and where they are coming from - and <b>more portable</b> -
 558 because namespace clashes cannot occur between LLVM code and other namespaces.
 559 The portability rule is important because different standard library
 560 implementations expose different symbols (potentially ones they shouldn't) and
 561 future revisions to the C++ standard will add more symbols to the std
 562 namespace.  As such, we never 'using namespace std;' in LLVM.</p>
 563
 564 <p>The exception to the general rule (i.e. it's not an exception for the std
 565 namespace) is for implementation files.  For example, all of the code in the
 566 LLVM project implements code that lives in the 'llvm' namespace.  As such, it
 567 is ok, and actually more clear, for the .cpp files to have a 'using namespace
 568 llvm' directive at their top, after the #includes.  The general form of this
 569 rule is that any .cpp file that implements code in any namespace may use that
 570 namespace (and its parents), but should not use any others.</p>
 571
 572 </div>
 573
 574 <!-- _______________________________________________________________________ -->
 575 <div class="doc_subsubsection">
 576   <a name="ll_virtual_anch">Provide a virtual method anchor for clases in headers</a>
 577 </div>
 578
 579 <div class="doc_text">
 580
 581 <p>If a class is defined in a header file and has a v-table (either it has
 582 virtual methods or it derives from classes with virtual methods), it must
 583 always have at least one out-of-line virtual method in the class.  Without
 584 this, the compiler will copy the vtable and RTTI into every .o file that
 585 #includes the header, bloating .o file sizes and increasing link times.
 586 </p>
 587
 588 </div>
 589
 590
 591 <!-- _______________________________________________________________________ -->
 592 <div class="doc_subsubsection">
 593   <a name="ll_preincrement">Prefer Preincrement</a>
 594 </div>
 595
 596 <div class="doc_text">
 597
 598 <p>Hard fast rule: Preincrement (<tt>++X</tt>) may be no slower than
 599 postincrement (<tt>X++</tt>) and could very well be a lot faster than it.  Use
 600 preincrementation whenever possible.</p>
 601
 602 <p>The semantics of postincrement include making a copy of the value being
 603 incremented, returning it, and then preincrementing the "work value".  For
 604 primitive types, this isn't a big deal... but for iterators, it can be a huge
 605 issue (for example, some iterators contains stack and set objects in them...
 606 copying an iterator could invoke the copy ctor's of these as well).  In general,
 607 get in the habit of always using preincrement, and you won't have a problem.</p>
 608
 609 </div>
 610
 611 <!-- _______________________________________________________________________ -->
 612 <div class="doc_subsubsection">
 613   <a name="ll_avoidendl">Avoid <tt>std::endl</tt></a>
 614 </div>
 615
 616 <div class="doc_text">
 617
 618 <p>The <tt>std::endl</tt> modifier, when used with iostreams outputs a newline
 619 to the output stream specified.  In addition to doing this, however, it also
 620 flushes the output stream.  In other words, these are equivalent:</p>
 621
 622 <div class="doc_code">
 623 <pre>
 624 std::cout &lt;&lt; std::endl;
 625 std::cout &lt;&lt; '\n' &lt;&lt; std::flush;
 626 </pre>
 627 </div>
 628
 629 <p>Most of the time, you probably have no reason to flush the output stream, so
 630 it's better to use a literal <tt>'\n'</tt>.</p>
 631
 632 </div>
 633
 634 <!-- *********************************************************************** -->
 635 <div class="doc_section">
 636   <a name="seealso">See Also</a>
 637 </div>
 638 <!-- *********************************************************************** -->
 639
 640 <div class="doc_text">
 641
 642 <p>A lot of these comments and recommendations have been culled for other
 643 sources.  Two particularly important books for our work are:</p>
 644
 645 <ol>
 646
 647 <li><a href="http://www.aw-bc.com/catalog/academic/product/0,1144,0201310155,00.html">Effective
 648 C++</a> by Scott Meyers.  There is an online version of the book (only some
 649 chapters though) <a
 650 href="http://www.awlonline.com/cseng/meyerscddemo/">available as well</a>.  Also
 651 interesting and useful are "More Effective C++" and "Effective STL" by the same
 652 author.</li>
 653
 654 <li><a href="http://cseng.aw.com/book/0,3828,0201633620,00.html">Large-Scale C++
 655 Software Design</a> by John Lakos</li>
 656
 657 </ol>
 658
 659 <p>If you get some free time, and you haven't read them: do so, you might learn
 660 something.</p>
 661
 662 </div>
 663
 664 <!-- *********************************************************************** -->
 665
 666 <hr>
 667 <address>
 668   <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
 669   src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
 670   <a href="http://validator.w3.org/check/referer"><img
 671   src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a>
 672
 673   <a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
 674   <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
 675   Last modified: $Date$
 676 </address>
 677
 678 </body>
 679 </html>