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