<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>
//
// 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.
//
//===----------------------------------------------------------------------===//
//
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
<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
include your module header <b>first</b> in the implementation file (as mentioned
<ol>
<li>The time to run the static c'tors impacts startup time of
- applications—a critical time for gui apps.</li>
+ 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 .o 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>
+ 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>
-<table align="center">
+<div align="center">
+<table>
<tbody>
<tr>
<th>Old Way</th>
<td align="left"><pre>DEBUG(std::cerr << ...);
DEBUG(dump(std::cerr));</pre></td>
<td align="left"><pre>DOUT << ...;
-dump(DOUT);</pre></td>
+DEBUG(dump(DOUT));</pre></td>
</tr>
<tr>
<td align="left"><pre>std::cerr << "Hello world\n";</pre></td>
<td align="left"><pre>std::cin >> Var;</pre></td>
<td align="left"><pre>llvm::cin >> Var;</pre></td>
</tr>
- <tr>
- <td align="left"><em>N/A</em></td>
- <td align="left"><pre>llvm::cnull >> Var;</pre>
- <ul><i>N.B.</i> Eats up argument <tt>Var</tt> outputting
- nothing.</ul></td>
- </tr>
<tr>
<td align="left"><pre>std::ostream</pre></td>
<td align="left"><pre>llvm::OStream</pre></td>
<td align="left"><pre>llvm::StringStream</pre></td>
</tr>
<tr>
- <td align="left"><pre>void print(std::ostream &Out);
+ <td align="left"><pre>void print(std::ostream &Out);
// ...
print(std::cerr);</pre></td>
- <td align="left"><pre>void print(std::ostream &Out);
-void print(std::ostream *Out) { if (Out) print(*Out) }
+ <td align="left"><pre>void print(llvm::OStream Out);<sup>1</sup>
// ...
print(llvm::cerr);</pre>
-<ul><i>N.B.</i> The second <tt>print</tt> method is called by the <tt>print</tt>
-expression. It prevents the execution of the first <tt>print</tt> method if the
-stream is <tt>cnull</tt>.</ul></td>
- </tbody>
-</table>
+</td> </tbody> </table>
+</div>
+
+<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>
</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>
<!-- _______________________________________________________________________ -->
<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>