diff options
| author | mike-m <mikem.llvm@gmail.com> | 2010-05-07 00:28:04 +0000 |
|---|---|---|
| committer | mike-m <mikem.llvm@gmail.com> | 2010-05-07 00:28:04 +0000 |
| commit | e2c3a49c8029ebd9ef530101cc24c66562e3dff5 (patch) | |
| tree | 91bf9600cc8df90cf99751a8f8bafc317cffc91e /docs/CodingStandards.html | |
| parent | c10b5afbe8138b0fdf3af4ed3e1ddf96cf3cb4cb (diff) | |
Revert r103213. It broke several sections of live website.
git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@103219 91177308-0d34-0410-b5e6-96231b3b80d8
Diffstat (limited to 'docs/CodingStandards.html')
| -rw-r--r-- | docs/CodingStandards.html | 1353 |
1 files changed, 1353 insertions, 0 deletions
diff --git a/docs/CodingStandards.html b/docs/CodingStandards.html new file mode 100644 index 0000000000..7815e19739 --- /dev/null +++ b/docs/CodingStandards.html @@ -0,0 +1,1353 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> +<html> +<head> + <link rel="stylesheet" href="llvm.css" type="text/css"> + <title>LLVM Coding Standards</title> +</head> +<body> + +<div class="doc_title"> + LLVM Coding Standards +</div> + +<ol> + <li><a href="#introduction">Introduction</a></li> + <li><a href="#mechanicalissues">Mechanical Source Issues</a> + <ol> + <li><a href="#sourceformating">Source Code Formatting</a> + <ol> + <li><a href="#scf_commenting">Commenting</a></li> + <li><a href="#scf_commentformat">Comment Formatting</a></li> + <li><a href="#scf_includes"><tt>#include</tt> Style</a></li> + <li><a href="#scf_codewidth">Source Code Width</a></li> + <li><a href="#scf_spacestabs">Use Spaces Instead of Tabs</a></li> + <li><a href="#scf_indentation">Indent Code Consistently</a></li> + </ol></li> + <li><a href="#compilerissues">Compiler Issues</a> + <ol> + <li><a href="#ci_warningerrors">Treat Compiler Warnings Like + Errors</a></li> + <li><a href="#ci_portable_code">Write Portable Code</a></li> + <li><a href="#ci_class_struct">Use of class/struct Keywords</a></li> + </ol></li> + </ol></li> + <li><a href="#styleissues">Style Issues</a> + <ol> + <li><a href="#macro">The High Level Issues</a> + <ol> + <li><a href="#hl_module">A Public Header File <b>is</b> a + Module</a></li> + <li><a href="#hl_dontinclude">#include as Little as Possible</a></li> + <li><a href="#hl_privateheaders">Keep "internal" Headers + Private</a></li> + <li><a href="#hl_earlyexit">Use Early Exits and 'continue' to Simplify + Code</a></li> + <li><a href="#hl_else_after_return">Don't use "else" after a + return</a></li> + <li><a href="#hl_predicateloops">Turn Predicate Loops into Predicate + Functions</a></li> + </ol></li> + <li><a href="#micro">The Low Level Issues</a> + <ol> + <li><a href="#ll_assert">Assert Liberally</a></li> + <li><a href="#ll_ns_std">Do not use 'using namespace std'</a></li> + <li><a href="#ll_virtual_anch">Provide a virtual method anchor for + classes in headers</a></li> + <li><a href="#ll_end">Don't evaluate end() every time through a + loop</a></li> + <li><a href="#ll_iostream"><tt>#include <iostream></tt> is + <em>forbidden</em></a></li> + <li><a href="#ll_avoidendl">Avoid <tt>std::endl</tt></a></li> + <li><a href="#ll_raw_ostream">Use <tt>raw_ostream</tt></a</li> + </ol></li> + + <li><a href="#nano">Microscopic Details</a> + <ol> + <li><a href="#micro_spaceparen">Spaces Before Parentheses</a></li> + <li><a href="#micro_preincrement">Prefer Preincrement</a></li> + <li><a href="#micro_namespaceindent">Namespace Indentation</a></li> + <li><a href="#micro_anonns">Anonymous Namespaces</a></li> + </ol></li> + + + </ol></li> + <li><a href="#seealso">See Also</a></li> +</ol> + +<div class="doc_author"> + <p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a></p> +</div> + + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="introduction">Introduction</a> +</div> +<!-- *********************************************************************** --> + +<div class="doc_text"> + +<p>This document attempts to describe a few coding standards that are being used +in the LLVM source tree. Although no coding standards should be regarded as +absolute requirements to be followed in all instances, coding standards can be +useful.</p> + +<p>This document intentionally does not prescribe fixed standards for religious +issues such as brace placement and space usage. For issues like this, follow +the golden rule:</p> + +<blockquote> + +<p><b><a name="goldenrule">If you are adding a significant body of source to a +project, feel free to use whatever style you are most comfortable with. If you +are extending, enhancing, or bug fixing already implemented code, use the style +that is already being used so that the source is uniform and easy to +follow.</a></b></p> + +</blockquote> + +<p>The ultimate goal of these guidelines is the increase readability and +maintainability of our common source base. If you have suggestions for topics to +be included, please mail them to <a +href="mailto:sabre@nondot.org">Chris</a>.</p> + +</div> + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="mechanicalissues">Mechanical Source Issues</a> +</div> +<!-- *********************************************************************** --> + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="sourceformating">Source Code Formatting</a> +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="scf_commenting">Commenting</a> +</div> + +<div class="doc_text"> + +<p>Comments are one critical part of readability and maintainability. Everyone +knows they should comment, so should you. When writing comments, write them as +English prose, which means they should use proper capitalization, punctuation, +etc. Although we all should probably +comment our code more than we do, there are a few very critical places that +documentation is very useful:</p> + +<b>File Headers</b> + +<p>Every source file should have a header on it that describes the basic +purpose of the file. If a file does not have a header, it should not be +checked into Subversion. Most source trees will probably have a standard +file header format. The standard format for the LLVM source tree looks like +this:</p> + +<div class="doc_code"> +<pre> +//===-- llvm/Instruction.h - Instruction class definition -------*- C++ -*-===// +// +// The LLVM Compiler Infrastructure +// +// This file is distributed under the University of Illinois Open Source +// License. See LICENSE.TXT for details. +// +//===----------------------------------------------------------------------===// +// +// This file contains the declaration of the Instruction class, which is the +// base class for all of the VM instructions. +// +//===----------------------------------------------------------------------===// +</pre> +</div> + +<p>A few things to note about this particular format: The "<tt>-*- C++ +-*-</tt>" string on the first line is there to tell Emacs that the source file +is a C++ file, not a C file (Emacs assumes .h files are C files by default). +Note that this tag is not necessary in .cpp files. The name of the file is also +on the first line, along with a very short description of the purpose of the +file. This is important when printing out code and flipping though lots of +pages.</p> + +<p>The next section in the file is a concise note that defines the license +that the file is released under. This makes it perfectly clear what terms the +source code can be distributed under and should not be modified in any way.</p> + +<p>The main body of the description does not have to be very long in most cases. +Here it's only two lines. If an algorithm is being implemented or something +tricky is going on, a reference to the paper where it is published should be +included, as well as any notes or "gotchas" in the code to watch out for.</p> + +<b>Class overviews</b> + +<p>Classes are one fundamental part of a good object oriented design. As such, +a class definition should have a comment block that explains what the class is +used for... if it's not obvious. If it's so completely obvious your grandma +could figure it out, it's probably safe to leave it out. Naming classes +something sane goes a long ways towards avoiding writing documentation.</p> + + +<b>Method information</b> + +<p>Methods defined in a class (as well as any global functions) should also be +documented properly. A quick note about what it does and a description of the +borderline behaviour is all that is necessary here (unless something +particularly tricky or insidious is going on). The hope is that people can +figure out how to use your interfaces without reading the code itself... that is +the goal metric.</p> + +<p>Good things to talk about here are what happens when something unexpected +happens: does the method return null? Abort? Format your hard disk?</p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="scf_commentformat">Comment Formatting</a> +</div> + +<div class="doc_text"> + +<p>In general, prefer C++ style (<tt>//</tt>) comments. They take less space, +require less typing, don't have nesting problems, etc. There are a few cases +when it is useful to use C style (<tt>/* */</tt>) comments however:</p> + +<ol> + <li>When writing a C code: Obviously if you are writing C code, use C style + comments.</li> + <li>When writing a header file that may be <tt>#include</tt>d by a C source + file.</li> + <li>When writing a source file that is used by a tool that only accepts C + style comments.</li> +</ol> + +<p>To comment out a large block of code, use <tt>#if 0</tt> and <tt>#endif</tt>. +These nest properly and are better behaved in general than C style comments.</p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="scf_includes"><tt>#include</tt> Style</a> +</div> + +<div class="doc_text"> + +<p>Immediately after the <a href="#scf_commenting">header file comment</a> (and +include guards if working on a header file), the <a +href="#hl_dontinclude">minimal</a> list of <tt>#include</tt>s required by the +file should be listed. We prefer these <tt>#include</tt>s to be listed in this +order:</p> + +<ol> + <li><a href="#mmheader">Main Module header</a></li> + <li><a href="#hl_privateheaders">Local/Private Headers</a></li> + <li><tt>llvm/*</tt></li> + <li><tt>llvm/Analysis/*</tt></li> + <li><tt>llvm/Assembly/*</tt></li> + <li><tt>llvm/Bytecode/*</tt></li> + <li><tt>llvm/CodeGen/*</tt></li> + <li>...</li> + <li><tt>Support/*</tt></li> + <li><tt>Config/*</tt></li> + <li>System <tt>#includes</tt></li> +</ol> + +<p>... and each category should be sorted by name.</p> + +<p><a name="mmheader">The "Main Module Header"</a> file applies to .cpp file +which implement an interface defined by a .h file. This <tt>#include</tt> +should always be included <b>first</b> regardless of where it lives on the file +system. By including a header file first in the .cpp files that implement the +interfaces, we ensure that the header does not have any hidden dependencies +which are not explicitly #included in the header, but should be. It is also a +form of documentation in the .cpp file to indicate where the interfaces it +implements are defined.</p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="scf_codewidth">Source Code Width</a> +</div> + +<div class="doc_text"> + +<p>Write your code to fit within 80 columns of text. This helps those of us who +like to print out code and look at your code in an xterm without resizing +it.</p> + +<p>The longer answer is that there must be some limit to the width of the code +in order to reasonably allow developers to have multiple files side-by-side in +windows on a modest display. If you are going to pick a width limit, it is +somewhat arbitrary but you might as well pick something standard. Going with +90 columns (for example) instead of 80 columns wouldn't add any significant +value and would be detrimental to printing out code. Also many other projects +have standardized on 80 columns, so some people have already configured their +editors for it (vs something else, like 90 columns).</p> + +<p>This is one of many contentious issues in coding standards, but is not up +for debate.</p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="scf_spacestabs">Use Spaces Instead of Tabs</a> +</div> + +<div class="doc_text"> + +<p>In all cases, prefer spaces to tabs in source files. People have different +preferred indentation levels, and different styles of indentation that they +like... this is fine. What isn't is that different editors/viewers expand tabs +out to different tab stops. This can cause your code to look completely +unreadable, and it is not worth dealing with.</p> + +<p>As always, follow the <a href="#goldenrule">Golden Rule</a> above: follow the +style of existing code if your are modifying and extending it. If you like four +spaces of indentation, <b>DO NOT</b> do that in the middle of a chunk of code +with two spaces of indentation. Also, do not reindent a whole source file: it +makes for incredible diffs that are absolutely worthless.</p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="scf_indentation">Indent Code Consistently</a> +</div> + +<div class="doc_text"> + +<p>Okay, your first year of programming you were told that indentation is +important. If you didn't believe and internalize this then, now is the time. +Just do it.</p> + +</div> + + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="compilerissues">Compiler Issues</a> +</div> + + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="ci_warningerrors">Treat Compiler Warnings Like Errors</a> +</div> + +<div class="doc_text"> + +<p>If your code has compiler warnings in it, something is wrong: you aren't +casting values correctly, your have "questionable" constructs in your code, or +you are doing something legitimately wrong. Compiler warnings can cover up +legitimate errors in output and make dealing with a translation unit +difficult.</p> + +<p>It is not possible to prevent all warnings from all compilers, nor is it +desirable. Instead, pick a standard compiler (like <tt>gcc</tt>) that provides +a good thorough set of warnings, and stick to them. At least in the case of +<tt>gcc</tt>, it is possible to work around any spurious errors by changing the +syntax of the code slightly. For example, an warning that annoys me occurs when +I write code like this:</p> + +<div class="doc_code"> +<pre> +if (V = getValue()) { + ... +} +</pre> +</div> + +<p><tt>gcc</tt> will warn me that I probably want to use the <tt>==</tt> +operator, and that I probably mistyped it. In most cases, I haven't, and I +really don't want the spurious errors. To fix this particular problem, I +rewrite the code like this:</p> + +<div class="doc_code"> +<pre> +if ((V = getValue())) { + ... +} +</pre> +</div> + +<p>...which shuts <tt>gcc</tt> up. Any <tt>gcc</tt> warning that annoys you can +be fixed by massaging the code appropriately.</p> + +<p>These are the <tt>gcc</tt> warnings that I prefer to enable: <tt>-Wall +-Winline -W -Wwrite-strings -Wno-unused</tt></p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="ci_portable_code">Write Portable Code</a> +</div> + +<div class="doc_text"> + +<p>In almost all cases, it is possible and within reason to write completely +portable code. If there are cases where it isn't possible to write portable +code, isolate it behind a well defined (and well documented) interface.</p> + +<p>In practice, this means that you shouldn't assume much about the host +compiler, including its support for "high tech" features like partial +specialization of templates. If these features are used, they should only be +an implementation detail of a library which has a simple exposed API.</p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> +<a name="ci_class_struct">Use of <tt>class</tt> and <tt>struct</tt> Keywords</a> +</div> +<div class="doc_text"> + +<p>In C++, the <tt>class</tt> and <tt>struct</tt> keywords can be used almost +interchangeably. The only difference is when they are used to declare a class: +<tt>class</tt> makes all members private by default while <tt>struct</tt> makes +all members public by default.</p> + +<p>Unfortunately, not all compilers follow the rules and some will generate +different symbols based on whether <tt>class</tt> or <tt>struct</tt> was used to +declare the symbol. This can lead to problems at link time.</p> + +<p>So, the rule for LLVM is to always use the <tt>class</tt> keyword, unless +<b>all</b> members are public and the type is a C++ "POD" type, in which case +<tt>struct</tt> is allowed.</p> + +</div> + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="styleissues">Style Issues</a> +</div> +<!-- *********************************************************************** --> + + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="macro">The High Level Issues</a> +</div> +<!-- ======================================================================= --> + + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="hl_module">A Public Header File <b>is</b> a Module</a> +</div> + +<div class="doc_text"> + +<p>C++ doesn't do too well in the modularity department. There is no real +encapsulation or data hiding (unless you use expensive protocol classes), but it +is what we have to work with. When you write a public header file (in the LLVM +source tree, they live in the top level "include" directory), you are defining a +module of functionality.</p> + +<p>Ideally, modules should be completely independent of each other, and their +header files should only include the absolute minimum number of headers +possible. A module is not just a class, a function, or a namespace: <a +href="http://www.cuj.com/articles/2000/0002/0002c/0002c.htm">it's a collection +of these</a> that defines an interface. This interface may be several +functions, classes or data structures, but the important issue is how they work +together.</p> + +<p>In general, a module should be implemented with one or more <tt>.cpp</tt> +files. Each of these <tt>.cpp</tt> files should include the header that defines +their interface first. This ensure that all of the dependences of the module +header have been properly added to the module header itself, and are not +implicit. System headers should be included after user headers for a +translation unit.</p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="hl_dontinclude"><tt>#include</tt> as Little as Possible</a> +</div> + +<div class="doc_text"> + +<p><tt>#include</tt> hurts compile time performance. Don't do it unless you +have to, especially in header files.</p> + +<p>But wait, sometimes you need to have the definition of a class to use it, or +to inherit from it. In these cases go ahead and <tt>#include</tt> that header +file. Be aware however that there are many cases where you don't need to have +the full definition of a class. If you are using a pointer or reference to a +class, you don't need the header file. If you are simply returning a class +instance from a prototyped function or method, you don't need it. In fact, for +most cases, you simply don't need the definition of a class... and not +<tt>#include</tt>'ing speeds up compilation.</p> + +<p>It is easy to try to go too overboard on this recommendation, however. You +<b>must</b> include all of the header files that you are using -- you can +include them either directly +or indirectly (through another header file). To make sure that you don't +accidentally forget to include a header file in your module header, make sure to +include your module header <b>first</b> in the implementation file (as mentioned +above). This way there won't be any hidden dependencies that you'll find out +about later...</p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="hl_privateheaders">Keep "internal" Headers Private</a> +</div> + +<div class="doc_text"> + +<p>Many modules have a complex implementation that causes them to use more than +one implementation (<tt>.cpp</tt>) file. It is often tempting to put the +internal communication interface (helper classes, extra functions, etc) in the +public module header file. Don't do this.</p> + +<p>If you really need to do something like this, put a private header file in +the same directory as the source files, and include it locally. This ensures +that your private interface remains private and undisturbed by outsiders.</p> + +<p>Note however, that it's okay to put extra implementation methods a public +class itself... just make them private (or protected), and all is well.</p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="hl_earlyexit">Use Early Exits and 'continue' to Simplify Code</a> +</div> + +<div class="doc_text"> + +<p>When reading code, keep in mind how much state and how many previous +decisions have to be remembered by the reader to understand a block of code. +Aim to reduce indentation where possible when it doesn't make it more difficult +to understand the code. One great way to do this is by making use of early +exits and the 'continue' keyword in long loops. As an example of using an early +exit from a function, consider this "bad" code:</p> + +<div class="doc_code"> +<pre> +Value *DoSomething(Instruction *I) { + if (!isa<TerminatorInst>(I) && + I->hasOneUse() && SomeOtherThing(I)) { + ... some long code .... + } + + return 0; +} +</pre> +</div> + +<p>This code has several problems if the body of the 'if' is large. When you're +looking at the top of the function, it isn't immediately clear that this +<em>only</em> does interesting things with non-terminator instructions, and only +applies to things with the other predicates. Second, it is relatively difficult +to describe (in comments) why these predicates are important because the if +statement makes it difficult to lay out the comments. Third, when you're deep +within the body of the code, it is indented an extra level. Finally, when +reading the top of the function, it isn't clear what the result is if the +predicate isn't true, you have to read to the end of the function to know that +it returns null.</p> + +<p>It is much preferred to format the code like this:</p> + +<div class="doc_code"> +<pre> +Value *DoSomething(Instruction *I) { + // Terminators never need 'something' done to them because, ... + if (isa<TerminatorInst>(I)) + return 0; + + // We conservatively avoid transforming instructions with multiple uses + // because goats like cheese. + if (!I->hasOneUse()) + return 0; + + // This is really just here for example. + if (!SomeOtherThing(I)) + return 0; + + ... some long code .... +} +</pre> +</div> + +<p>This fixes these problems. A similar problem frequently happens in for +loops. A silly example is something like this:</p> + +<div class="doc_code"> +<pre> + for (BasicBlock::iterator II = BB->begin(), E = BB->end(); II != E; ++II) { + if (BinaryOperator *BO = dyn_cast<BinaryOperator>(II)) { + Value *LHS = BO->getOperand(0); + Value *RHS = BO->getOperand(1); + if (LHS != RHS) { + ... + } + } + } +</pre> +</div> + +<p>When you have very very small loops, this sort of structure is fine, but if +it exceeds more than 10-15 lines, it becomes difficult for people to read and +understand at a glance. +The problem with this sort of code is that it gets very nested very quickly, +meaning that the reader of the code has to keep a lot of context in their brain +to remember what is going immediately on in the loop, because they don't know +if/when the if conditions will have elses etc. It is strongly preferred to +structure the loop like this:</p> + +<div class="doc_code"> +<pre> + for (BasicBlock::iterator II = BB->begin(), E = BB->end(); II != E; ++II) { + BinaryOperator *BO = dyn_cast<BinaryOperator>(II); + if (!BO) continue; + + Value *LHS = BO->getOperand(0); + Value *RHS = BO->getOperand(1); + if (LHS == RHS) continue; + } +</pre> +</div> + +<p>This has all the benefits of using early exits from functions: it reduces +nesting of the loop, it makes it easier to describe why the conditions are true, +and it makes it obvious to the reader that there is no "else" coming up that +they have to push context into their brain for. If a loop is large, this can +be a big understandability win.</p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="hl_else_after_return">Don't use "else" after a return</a> +</div> + +<div class="doc_text"> + +<p>For similar reasons above (reduction of indentation and easier reading), + please do not use "else" or "else if" after something that interrupts + control flow like return, break, continue, goto, etc. For example, this is + "bad":</p> + +<div class="doc_code"> +<pre> + case 'J': { + if (Signed) { + Type = Context.getsigjmp_bufType(); + if (Type.isNull()) { + Error = ASTContext::GE_Missing_sigjmp_buf; + return QualType(); + } else { + break; + } + } else { + Type = Context.getjmp_bufType(); + if (Type.isNull()) { + Error = ASTContext::GE_Missing_jmp_buf; + return QualType(); + } else { + break; + } + } + } + } +</pre> +</div> + +<p>It is better to write this something like:</p> + +<div class="doc_code"> +<pre> + case 'J': + if (Signed) { + Type = Context.getsigjmp_bufType(); + if (Type.isNull()) { + Error = ASTContext::GE_Missing_sigjmp_buf; + return QualType(); + } + } else { + Type = Context.getjmp_bufType(); + if (Type.isNull()) { + Error = ASTContext::GE_Missing_jmp_buf; + return QualType(); + } + } + break; +</pre> +</div> + +<p>Or better yet (in this case), as:</p> + +<div class="doc_code"> +<pre> + case 'J': + if (Signed) + Type = Context.getsigjmp_bufType(); + else + Type = Context.getjmp_bufType(); + + if (Type.isNull()) { + Error = Signed ? ASTContext::GE_Missing_sigjmp_buf : + ASTContext::GE_Missing_jmp_buf; + return QualType(); + } + break; +</pre> +</div> + +<p>The idea is to reduce indentation and the amount of code you have to keep + track of when reading the code.</p> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="hl_predicateloops">Turn Predicate Loops into Predicate Functions</a> +</div> + +<div class="doc_text"> + +<p>It is very common to write small loops that just compute a boolean + value. There are a number of ways that people commonly write these, but an + example of this sort of thing is:</p> + +<div class="doc_code"> +<pre> + <b>bool FoundFoo = false;</b> + for (unsigned i = 0, e = BarList.size(); i != e; ++i) + if (BarList[i]->isFoo()) { + <b>FoundFoo = true;</b> + break; + } + + <b>if (FoundFoo) {</b> + ... + } +</pre> +</div> + +<p>This sort of code is awkward to write, and is almost always a bad sign. +Instead of this sort of loop, we strongly prefer to use a predicate function +(which may be <a href="#micro_anonns">static</a>) that uses +<a href="#hl_earlyexit">early exits</a> to compute the predicate. We prefer +the code to be structured like this: +</p> + + +<div class="doc_code"> +<pre> +/// ListContainsFoo - Return true if the specified list has an element that is +/// a foo. +static bool ListContainsFoo(const std::vector<Bar*> &List) { + for (unsigned i = 0, e = List.size(); i != e; ++i) + if (List[i]->isFoo()) + return true; + return false; +} +... + + <b>if (ListContainsFoo(BarList)) {</b> + ... + } +</pre> +</div> + +<p>There are many reasons for doing this: it reduces indentation and factors out +code which can often be shared by other code that checks for the same predicate. +More importantly, it <em>forces you to pick a name</em> for the function, and +forces you to write a comment for it. In this silly example, this doesn't add +much value. However, if the condition is complex, this can make it a lot easier +for the reader to understand the code that queries for this predicate. Instead +of being faced with the in-line details of how we check to see if the BarList +contains a foo, we can trust the function name and continue reading with better +locality.</p> + +</div> + + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="micro">The Low Level Issues</a> +</div> +<!-- ======================================================================= --> + + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="ll_assert">Assert Liberally</a> +</div> + +<div class="doc_text"> + +<p>Use the "<tt>assert</tt>" function to its fullest. Check all of your +preconditions and assumptions, you never know when a bug (not necessarily even +yours) might be caught early by an assertion, which reduces debugging time +dramatically. The "<tt><cassert></tt>" header file is probably already +included by the header files you are using, so it doesn't cost anything to use +it.</p> + +<p>To further assist with debugging, make sure to put some kind of error message +in the assertion statement (which is printed if the assertion is tripped). This +helps the poor debugging make sense of why an assertion is being made and +enforced, and hopefully what to do about it. Here is one complete example:</p> + +<div class="doc_code"> +<pre> +inline Value *getOperand(unsigned i) { + assert(i < Operands.size() && "getOperand() out of range!"); + return Operands[i]; +} +</pre> +</div> + +<p>Here are some examples:</p> + +<div class="doc_code"> +<pre> +assert(Ty->isPointerType() && "Can't allocate a non pointer type!"); + +assert((Opcode == Shl || Opcode == Shr) && "ShiftInst Opcode invalid!"); + +assert(idx < getNumSuccessors() && "Successor # out of range!"); + +assert(V1.getType() == V2.getType() && "Constant types must be identical!"); + +assert(isa<PHINode>(Succ->front()) && "Only works on PHId BBs!"); +</pre> +</div> + +<p>You get the idea...</p> + +<p>Please be aware when adding assert statements that not all compilers are aware of +the semantics of the assert. In some places, asserts are used to indicate a piece of +code that should not be reached. These are typically of the form:</p> + +<div class="doc_code"> +<pre> +assert(0 && "Some helpful error message"); +</pre> +</div> + +<p>When used in a function that returns a value, they should be followed with a return +statement and a comment indicating that this line is never reached. This will prevent +a compiler which is unable to deduce that the assert statement never returns from +generating a warning.</p> + +<div class="doc_code"> +<pre> +assert(0 && "Some helpful error message"); +// Not reached +return 0; +</pre> +</div> + +</div> + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> + <a name="ll_ns_std">Do not use '<tt>using namespace std</tt>'</a> +</div> + +<div class="doc_text"> +<p>In LLVM, we prefer to explicitly prefix all identifiers from the standard +namespace with an "<tt>std::</tt>" prefix, rather than rely on +"<tt>using namespace std;</tt>".</p> + +<p> In header files, adding a '<tt>using namespace XXX</tt>' directive pollutes +the namespace of any source file that <tt>#include</tt>s the header. This is +clearly a bad thing.</p> + +<p>In implementation files (e.g. .cpp files), the rule is more of a stylistic +rule, but is still important. Basically, using explicit namespace prefixes +makes the code <b>clearer</b>, because it is immediately obvious what facilities +are being used and where they are coming from, and <b>more portable</b>, because +namespace clashes cannot occur between LLVM code and other namespaces. The +portability rule is important because different standard library implementations +expose different symbols (potentially ones they shouldn't), and future re |