Add missing newlines at EOF (for clang++).
[oota-llvm.git] / docs / CodingStandards.html
index 2068c0f2c5a1532211875008782e9e928e15cace..ee9443d164d5a55284f49b063dfedd4dae7e9e46 100644 (file)
@@ -43,6 +43,8 @@
               Private</a></li>
           <li><a href="#hl_earlyexit">Use Early Exits and 'continue' to Simplify
               Code</a></li>
               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="#hl_predicateloops">Turn Predicate Loops into Predicate
               Functions</a></li>
         </ol></li>
@@ -57,6 +59,7 @@
           <li><a href="#ll_iostream"><tt>#include &lt;iostream&gt;</tt> is
               <em>forbidden</em></a></li>
           <li><a href="#ll_avoidendl">Avoid <tt>std::endl</tt></a></li>
           <li><a href="#ll_iostream"><tt>#include &lt;iostream&gt;</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>
         
       <li><a href="#nano">Microscopic Details</a>
@@ -300,7 +303,7 @@ for debate.</p>
 <div class="doc_text">
 
 <p>In all cases, prefer spaces to tabs in source files.  People have different
 <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>
 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>
@@ -416,7 +419,8 @@ different symbols based on whether <tt>class</tt> or <tt>struct</tt> was used to
 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
 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>
 
@@ -487,7 +491,7 @@ most cases, you simply don't need the definition of a class... and not
 <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
 <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>
 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>
@@ -623,6 +627,88 @@ be a big understandability win.</p>
 
 </div>
 
 
 </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">
 
 <!-- _______________________________________________________________________ -->
 <div class="doc_subsubsection">
@@ -704,7 +790,7 @@ locality.</p>
 <div class="doc_text">
 
 <p>Use the "<tt>assert</tt>" function to its fullest.  Check all of your
 <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>&lt;cassert&gt;</tt>" header file is probably already
 included by the header files you are using, so it doesn't cost anything to use
 yours) might be caught early by an assertion, which reduces debugging time
 dramatically.  The "<tt>&lt;cassert&gt;</tt>" header file is probably already
 included by the header files you are using, so it doesn't cost anything to use
@@ -904,12 +990,14 @@ library. There are two problems with this:</p>
 </ol>
 
 <p>Note that using the other stream headers (<tt>&lt;sstream&gt;</tt> for
 </ol>
 
 <p>Note that using the other stream headers (<tt>&lt;sstream&gt;</tt> for
-example) is allowed normally, it is just <tt>&lt;iostream&gt;</tt> that is
-causing problems.</p>
+example) is not problematic in this regard (just <tt>&lt;iostream&gt;</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>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>
+<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>
 
@@ -938,6 +1026,26 @@ it's better to use a literal <tt>'\n'</tt>.</p>
 </div>
 
 
 </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 class="doc_subsection">
   <a name="nano">Microscopic Details</a>