<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="#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_preincrement">Prefer Preincrement</a></li>
<li><a href="#ll_avoidendl">Avoid <tt>std::endl</tt></a></li>
</ol></li>
<div class="doc_code">
<pre>
//===-- llvm/Instruction.h - Instruction class definition -------*- C++ -*-===//
-//
+//
// The LLVM Compiler Infrastructure
//
-// This file was developed by <whoever started the file> 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
</pre>
</div>
-<p>A few things to note about this particular format: The 'developed by' line
-should be the name of the person or organization who initially contributed the
-file. The "<tt>-*- C++
+<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
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
<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>
<!-- _______________________________________________________________________ -->
<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>
put more pressure on the VM system on low-memory machines.</li>
</ol>
-<div align="center">
-<table>
- <tbody>
- <tr>
- <th>Old Way</th>
- <th>New Way</th>
- </tr>
- <tr>
- <td align="left"><pre>#include <iostream></pre></td>
- <td align="left"><pre>#include "llvm/Support/Streams.h"</pre></td>
- </tr>
- <tr>
- <td align="left"><pre>DEBUG(std::cerr << ...);
-DEBUG(dump(std::cerr));</pre></td>
- <td align="left"><pre>DOUT << ...;
-DEBUG(dump(DOUT));</pre></td>
- </tr>
- <tr>
- <td align="left"><pre>std::cerr << "Hello world\n";</pre></td>
- <td align="left"><pre>llvm::cerr << "Hello world\n";</pre></td>
- </tr>
- <tr>
- <td align="left"><pre>std::cout << "Hello world\n";</pre></td>
- <td align="left"><pre>llvm::cout << "Hello world\n";</pre></td>
- </tr>
- <tr>
- <td align="left"><pre>std::cin >> Var;</pre></td>
- <td align="left"><pre>llvm::cin >> Var;</pre></td>
- </tr>
- <tr>
- <td align="left"><pre>std::ostream</pre></td>
- <td align="left"><pre>llvm::OStream</pre></td>
- </tr>
- <tr>
- <td align="left"><pre>std::istream</pre></td>
- <td align="left"><pre>llvm::IStream</pre></td>
- </tr>
- <tr>
- <td align="left"><pre>std::stringstream</pre></td>
- <td align="left"><pre>llvm::StringStream</pre></td>
- </tr>
- <tr>
- <td align="left"><pre>void print(std::ostream &Out);
-// ...
-print(std::cerr);</pre></td>
- <td align="left"><pre>void print(llvm::OStream Out);<sup>1</sup>
-// ...
-print(llvm::cerr);</pre>
-
-</td> </tbody> </table>
-</div>
+<p>Note that using the other stream headers (<tt><sstream></tt> for
+example) is allowed normally, it is just <tt><iostream></tt> that is
+causing problems.</p>
-<div class="doc_text">
-<p><sup>1</sup><tt>llvm::OStream</tt> is a light-weight class so it should never
-be passed by reference. This is important because in some configurations,
-<tt>DOUT</tt> is an rvalue.</p>
-</div>
+<p>The preferred replacement for stream functionality is the
+<tt>llvm::raw_ostream</tt> class (for writing to output streams of various
+sorts) and the <tt>llvm::MemoryBuffer</tt> API (for reading in files).</p>
</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>
<!-- _______________________________________________________________________ -->
"<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 includes the header. This is clearly a
-bad thing.</p>
+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
<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>
<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>