<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 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
<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>
<div class="doc_code">
<pre>
-assert(0 && "Some helpful error message");
+assert(0 && "Some helpful error message");
</pre>
</div>
<div class="doc_code">
<pre>
-assert(0 && "Some helpful error message");
+assert(0 && "Some helpful error message");
// Not reached
return 0;
</pre>
"<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>
projects / oota-llvm.git / blobdiff