MSVC: Disable 4351, a completely useless warning: "warning: I'm not miscompiling

[oota-llvm.git] / docs / CodingStandards.html

diff --git a/docs/CodingStandards.html b/docs/CodingStandards.html
index 0aab5c7b671e74f3d51cf508ed06277601405fa8..79c816ef65f3fbfc3add9b5f70bbc3f35d34fab2 100644 (file)
--- a/docs/CodingStandards.html
+++ b/docs/CodingStandards.html
@@ -50,6 +50,8 @@
           <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>
@@ -116,7 +118,9 @@ href="mailto:sabre@nondot.org">Chris</a>.</p>
 <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>
 
@@ -526,8 +530,8 @@ example) is allowed normally, it is just <tt>&lt;iostream&gt;</tt> that is
 causing problems.</p>
 
 <p>The preferred replacement for stream functionality is the
-<tt>raw_ostream</tt> class (for writing to output streams of various sorts) and
-the MemoryBuffer API (for reading in files).</p>
+<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>
 
@@ -661,6 +665,67 @@ 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">