<html>
<head>
<link rel="stylesheet" href="llvm.css" type="text/css">
- <title>A Few Coding Standards</title>
+ <title>LLVM Coding Standards</title>
</head>
<body>
<div class="doc_title">
- A Few Coding Standards
+ LLVM Coding Standards
</div>
<ol>
<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 clases in headers</a></li>
- <li><a href="#ll_preincrement">Prefer Preincrement</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_text">
<p>Comments are one critical part of readability and maintainability. Everyone
-knows they should comment, so should you. Although we all should probably
+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 CVS. Most source trees will probably have a standard
+<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 was developed by the LLVM research group and is distributed under
-// the University of Illinois Open Source License. See LICENSE.TXT for details.
-//
+// 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
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.</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
<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 any a description of the
+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 insideous is going on). The hope is that people can
+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>
<li>System <tt>#includes</tt></li>
</ol>
-<p>... and each catagory should be sorted by name.</p>
+<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>
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_text">
<p>In all cases, prefer spaces to tabs in source files. People have different
-prefered indentation levels, and different styles of indentation that they
+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>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. In fact, Visual C++ 6 could be an important target
-for our work in the future, and we don't want to have to rewrite all of our code
-to support it.</p>
+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>
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, in which case <tt>struct</tt> is allowed.</p>
+<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_subsection">
<a name="macro">The High Level Issues</a>
</div>
+<!-- ======================================================================= -->
<!-- _______________________________________________________________________ -->
<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, either directly
+<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
-accidently forget to include a header file in your module header, make sure to
+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_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_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 neccesarily even
+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
<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 'using namespace std'</a>
+ <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 "std::" prefix, rather than rely on "using namespace std;".
-</p>
-
-<p> In header files, adding a 'using namespace XXX' directive pollutes the
-namespace of any source file that includes 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>more clear</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 revisions to the C++ standard will add more symbols to the std
-namespace. As such, we never 'using namespace std;' in LLVM.</p>
-
-<p>The exception to the general rule (i.e. it's not an exception for the std
-namespace) is for implementation files. For example, all of the code in the
-LLVM project implements code that lives in the 'llvm' namespace. As such, it
-is ok, and actually more clear, for the .cpp files to have a 'using namespace
-llvm' directive at their top, after the #includes. The general form of this
-rule is that any .cpp file that implements code in any namespace may use that
-namespace (and its parents), but should not use any others.</p>
+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 revisions
+to the C++ standard will add more symbols to the <tt>std</tt> namespace. As
+such, we never use '<tt>using namespace std;</tt>' in LLVM.</p>
+
+<p>The exception to the general rule (i.e. it's not an exception for
+the <tt>std</tt> namespace) is for implementation files. For example, all of
+the code in the LLVM project implements code that lives in the 'llvm' namespace.
+As such, it is ok, and actually clearer, for the .cpp files to have a '<tt>using
+namespace llvm</tt>' directive at their top, after the <tt>#include</tt>s. The
+general form of this rule is that any .cpp file that implements code in any
+namespace may use that namespace (and its parents'), but should not use any
+others.</p>
</div>
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
- <a name="ll_virtual_anch">Provide a virtual method anchor for clases in headers</a>
+ <a name="ll_virtual_anch">Provide a virtual method anchor for classes
+ in headers</a>
</div>
<div class="doc_text">
<p>If a class is defined in a header file and has a v-table (either it has
virtual methods or it derives from classes with virtual methods), it must
always have at least one out-of-line virtual method in the class. Without
-this, the compiler will copy the vtable and RTTI into every .o file that
-#includes the header, bloating .o file sizes and increasing link times.
-</p>
+this, the compiler will copy the vtable and RTTI into every <tt>.o</tt> file
+that <tt>#include</tt>s the header, bloating <tt>.o</tt> file sizes and
+increasing link times.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="ll_end">Don't evaluate end() every time through a loop</a>
+</div>
+
+<div class="doc_text">
+
+<p>Because C++ doesn't have a standard "foreach" loop (though it can be emulated
+with macros and may be coming in C++'0x) we end up writing a lot of loops that
+manually iterate from begin to end on a variety of containers or through other
+data structures. One common mistake is to write a loop in this style:</p>
+
+<div class="doc_code">
+<pre>
+ BasicBlock *BB = ...
+ for (BasicBlock::iterator I = BB->begin(); I != <b>BB->end()</b>; ++I)
+ ... use I ...
+</pre>
+</div>
+
+<p>The problem with this construct is that it evaluates "<tt>BB->end()</tt>"
+every time through the loop. Instead of writing the loop like this, we strongly
+prefer loops to be written so that they evaluate it once before the loop starts.
+A convenient way to do this is like so:</p>
+
+<div class="doc_code">
+<pre>
+ BasicBlock *BB = ...
+ for (BasicBlock::iterator I = BB->begin(), E = <b>BB->end()</b>; I != E; ++I)
+ ... use I ...
+</pre>
+</div>
+
+<p>The observant may quickly point out that these two loops may have different
+semantics: if the container (a basic block in this case) is being mutated, then
+"<tt>BB->end()</tt>" may change its value every time through the loop and the
+second loop may not in fact be correct. If you actually do depend on this
+behavior, please write the loop in the first form and add a comment indicating
+that you did it intentionally.</p>
+
+<p>Why do we prefer the second form (when correct)? Writing the loop in the
+first form has two problems: First it may be less efficient than evaluating it
+at the start of the loop. In this case, the cost is probably minor: a few extra
+loads every time through the loop. However, if the base expression is more
+complex, then the cost can rise quickly. I've seen loops where the end
+expression was actually something like: "<tt>SomeMap[x]->end()</tt>" and map
+lookups really aren't cheap. By writing it in the second form consistently, you
+eliminate the issue entirely and don't even have to think about it.</p>
+
+<p>The second (even bigger) issue is that writing the loop in the first form
+hints to the reader that the loop is mutating the container (a fact that a
+comment would handily confirm!). If you write the loop in the second form, it
+is immediately obvious without even looking at the body of the loop that the
+container isn't being modified, which makes it easier to read the code and
+understand what it does.</p>
+
+<p>While the second form of the loop is a few extra keystrokes, we do strongly
+prefer it.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="ll_iostream"><tt>#include <iostream></tt> is forbidden</a>
+</div>
+
+<div class="doc_text">
+
+<p>The use of <tt>#include <iostream></tt> in library files is
+hereby <b><em>forbidden</em></b>. The primary reason for doing this is to
+support clients using LLVM libraries as part of larger systems. In particular,
+we statically link LLVM into some dynamic libraries. Even if LLVM isn't used,
+the static c'tors are run whenever an application start up that uses the dynamic
+library. There are two problems with this:</p>
+
+<ol>
+ <li>The time to run the static c'tors impacts startup time of
+ applications—a critical time for GUI apps.</li>
+ <li>The static c'tors cause the app to pull many extra pages of memory off the
+ disk: both the code for the static c'tors in each <tt>.o</tt> file and the
+ small amount of data that gets touched. In addition, touched/dirty pages
+ put more pressure on the VM system on low-memory machines.</li>
+</ol>
+
+<p>Note that using the other stream headers (<tt><sstream></tt> for
+example) is not problematic in this regard (just <tt><iostream></tt>).
+However, raw_ostream provides various APIs that are better performing for almost
+every use than std::ostream style APIs, so you should just use it for new
+code.</p>
+
+<p><b>New code should always
+use <a href="#ll_raw_ostream"><tt>raw_ostream</tt></a> for writing, or
+the <tt>llvm::MemoryBuffer</tt> API for reading files.</b></p>
+
+</div>
+
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="ll_avoidendl">Avoid <tt>std::endl</tt></a>
+</div>
+
+<div class="doc_text">
+
+<p>The <tt>std::endl</tt> modifier, when used with iostreams outputs a newline
+to the output stream specified. In addition to doing this, however, it also
+flushes the output stream. In other words, these are equivalent:</p>
+
+<div class="doc_code">
+<pre>
+std::cout << std::endl;
+std::cout << '\n' << std::flush;
+</pre>
+</div>
+
+<p>Most of the time, you probably have no reason to flush the output stream, so
+it's better to use a literal <tt>'\n'</tt>.</p>
+
+</div>
+
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="ll_raw_ostream">Use <tt>raw_ostream</tt></a>
+</div>
+
+<div class="doc_text">
+
+<p>LLVM includes a lightweight, simple, and efficient stream implementation
+in <tt>llvm/Support/raw_ostream.h</tt> which provides all of the common features
+of <tt>std::ostream</tt>. All new code should use <tt>raw_ostream</tt> instead
+of <tt>ostream</tt>.</p>
+
+<p>Unlike <tt>std::ostream</tt>, <tt>raw_ostream</tt> is not a template and can
+be forward declared as <tt>class raw_ostream</tt>. Public headers should
+generally not include the <tt>raw_ostream</tt> header, but use forward
+declarations and constant references to <tt>raw_ostream</tt> instances.</p>
+
+</div>
+
+
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="nano">Microscopic Details</a>
+</div>
+<!-- ======================================================================= -->
+
+<p>This section describes preferred low-level formatting guidelines along with
+reasoning on why we prefer them.</p>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="micro_spaceparen">Spaces Before Parentheses</a>
+</div>
+
+<div class="doc_text">
+
+<p>We prefer to put a space before a parentheses only in control flow
+statements, but not in normal function call expressions and function-like
+macros. For example, this is good:</p>
+
+<div class="doc_code">
+<pre>
+ <b>if (</b>x) ...
+ <b>for (</b>i = 0; i != 100; ++i) ...
+ <b>while (</b>llvm_rocks) ...
+
+ <b>somefunc(</b>42);
+ <b><a href="#ll_assert">assert</a>(</b>3 != 4 && "laws of math are failing me");
+
+ a = <b>foo(</b>42, 92) + <b>bar(</b>x);
+ </pre>
+</div>
+
+<p>... and this is bad:</p>
+
+<div class="doc_code">
+<pre>
+ <b>if(</b>x) ...
+ <b>for(</b>i = 0; i != 100; ++i) ...
+ <b>while(</b>llvm_rocks) ...
+
+ <b>somefunc (</b>42);
+ <b><a href="#ll_assert">assert</a> (</b>3 != 4 && "laws of math are failing me");
+
+ a = <b>foo (</b>42, 92) + <b>bar (</b>x);
+</pre>
+</div>
+<p>The reason for doing this is not completely arbitrary. This style makes
+ control flow operators stand out more, and makes expressions flow better. The
+ function call operator binds very tightly as a postfix operator. Putting
+ a space after a function name (as in the last example) makes it appear that
+ the code might bind the arguments of the left-hand-side of a binary operator
+ with the argument list of a function and the name of the right side. More
+ specifically, it is easy to misread the "a" example as:</p>
+
+<div class="doc_code">
+<pre>
+ a = foo <b>(</b>(42, 92) + bar<b>)</b> (x);
+</pre>
</div>
+<p>... when skimming through the code. By avoiding a space in a function, we
+avoid this misinterpretation.</p>
+
+</div>
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
- <a name="ll_preincrement">Prefer Preincrement</a>
+ <a name="micro_preincrement">Prefer Preincrement</a>
</div>
<div class="doc_text">
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
- <a name="ll_avoidendl">Avoid <tt>std::endl</tt></a>
+ <a name="micro_namespaceindent">Namespace Indentation</a>
</div>
<div class="doc_text">
-<p>The <tt>std::endl</tt> modifier, when used with iostreams outputs a newline
-to the output stream specified. In addition to doing this, however, it also
-flushes the output stream. In other words, these are equivalent:</p>
+<p>
+In general, we strive to reduce indentation where ever possible. This is useful
+because we want code to <a href="#scf_codewidth">fit into 80 columns</a> without
+wrapping horribly, but also because it makes it easier to understand the code.
+Namespaces are a funny thing: they are often large, and we often desire to put
+lots of stuff into them (so they can be large). Other times they are tiny,
+because they just hold an enum or something similar. In order to balance this,
+we use different approaches for small versus large namespaces.
+</p>
+
+<p>
+If a namespace definition is small and <em>easily</em> fits on a screen (say,
+less than 35 lines of code), then you should indent its body. Here's an
+example:
+</p>
<div class="doc_code">
<pre>
-std::cout << std::endl;
-std::cout << '\n' << std::flush;
+namespace llvm {
+ namespace X86 {
+ /// RelocationType - An enum for the x86 relocation codes. Note that
+ /// the terminology here doesn't follow x86 convention - word means
+ /// 32-bit and dword means 64-bit.
+ enum RelocationType {
+ /// reloc_pcrel_word - PC relative relocation, add the relocated value to
+ /// the value already in memory, after we adjust it for where the PC is.
+ reloc_pcrel_word = 0,
+
+ /// reloc_picrel_word - PIC base relative relocation, add the relocated
+ /// value to the value already in memory, after we adjust it for where the
+ /// PIC base is.
+ reloc_picrel_word = 1,
+
+ /// reloc_absolute_word, reloc_absolute_dword - Absolute relocation, just
+ /// add the relocated value to the value already in memory.
+ reloc_absolute_word = 2,
+ reloc_absolute_dword = 3
+ };
+ }
+}
</pre>
</div>
-<p>Most of the time, you probably have no reason to flush the output stream, so
-it's better to use a literal <tt>'\n'</tt>.</p>
+<p>Since the body is small, indenting adds value because it makes it very clear
+where the namespace starts and ends, and it is easy to take the whole thing in
+in one "gulp" when reading the code. If the blob of code in the namespace is
+larger (as it typically is in a header in the llvm or clang namespaces), do not
+indent the code, and add a comment indicating what namespace is being closed.
+For example:</p>
+
+<div class="doc_code">
+<pre>
+namespace llvm {
+namespace knowledge {
+
+/// Grokable - This class represents things that Smith can have an intimate
+/// understanding of and contains the data associated with it.
+class Grokable {
+...
+public:
+ explicit Grokable() { ... }
+ virtual ~Grokable() = 0;
+
+ ...
+
+};
+
+} // end namespace knowledge
+} // end namespace llvm
+</pre>
+</div>
+
+<p>Because the class is large, we don't expect that the reader can easily
+understand the entire concept in a glance, and the end of the file (where the
+namespaces end) may be a long ways away from the place they open. As such,
+indenting the contents of the namespace doesn't add any value, and detracts from
+the readability of the class. In these cases it is best to <em>not</em> indent
+the contents of the namespace.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="micro_anonns">Anonymous Namespaces</a>
+</div>
+
+<div class="doc_text">
+
+<p>After talking about namespaces in general, you may be wondering about
+anonymous namespaces in particular.
+Anonymous namespaces are a great language feature that tells the C++ compiler
+that the contents of the namespace are only visible within the current
+translation unit, allowing more aggressive optimization and eliminating the
+possibility of symbol name collisions. Anonymous namespaces are to C++ as
+"static" is to C functions and global variables. While "static" is available
+in C++, anonymous namespaces are more general: they can make entire classes
+private to a file.</p>
+
+<p>The problem with anonymous namespaces is that they naturally want to
+encourage indentation of their body, and they reduce locality of reference: if
+you see a random function definition in a C++ file, it is easy to see if it is
+marked static, but seeing if it is in an anonymous namespace requires scanning
+a big chunk of the file.</p>
+
+<p>Because of this, we have a simple guideline: make anonymous namespaces as
+small as possible, and only use them for class declarations. For example, this
+is good:</p>
+
+<div class="doc_code">
+<pre>
+<b>namespace {</b>
+ class StringSort {
+ ...
+ public:
+ StringSort(...)
+ bool operator<(const char *RHS) const;
+ };
+<b>} // end anonymous namespace</b>
+
+static void Helper() {
+ ...
+}
+
+bool StringSort::operator<(const char *RHS) const {
+ ...
+}
+
+</pre>
+</div>
+
+<p>This is bad:</p>
+
+
+<div class="doc_code">
+<pre>
+<b>namespace {</b>
+class StringSort {
+...
+public:
+ StringSort(...)
+ bool operator<(const char *RHS) const;
+};
+
+void Helper() {
+ ...
+}
+
+bool StringSort::operator<(const char *RHS) const {
+ ...
+}
+
+<b>} // end anonymous namespace</b>
+
+</pre>
+</div>
+
+
+<p>This is bad specifically because if you're looking at "Helper" in the middle
+of a large C++ file, that you have no immediate way to tell if it is local to
+the file. When it is marked static explicitly, this is immediately obvious.
+Also, there is no reason to enclose the definition of "operator<" in the
+namespace just because it was declared there.
+</p>
</div>
+
+
<!-- *********************************************************************** -->
<div class="doc_section">
<a name="seealso">See Also</a>
<ol>
-<li><a href="http://www.aw-bc.com/catalog/academic/product/0,1144,0201310155,00.html">Effective
-C++</a> by Scott Meyers. There is an online version of the book (only some
-chapters though) <a
-href="http://www.awlonline.com/cseng/meyerscddemo/">available as well</a>. Also
+<li><a href="http://www.amazon.com/Effective-Specific-Addison-Wesley-Professional-Computing/dp/0321334876">Effective
+C++</a> by Scott Meyers. Also
interesting and useful are "More Effective C++" and "Effective STL" by the same
author.</li>
-<li><a href="http://cseng.aw.com/book/0,3828,0201633620,00.html">Large-Scale C++
-Software Design</a> by John Lakos</li>
+<li>Large-Scale C++ Software Design by John Lakos</li>
</ol>
<hr>
<address>
<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
- src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
+ src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
<a href="http://validator.w3.org/check/referer"><img
- src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a>
+ src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
<a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
<a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
projects / oota-llvm.git / blobdiff