clarify the coding standards a bit.

git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@152957 91177308-0d34-0410-b5e6-96231b3b80d8

docs/CodingStandards.html

@@ -85,17 +85,16 @@
 
 
 <!-- *********************************************************************** -->
-<h2>
-  <a name="introduction">Introduction</a>
-</h2>
+<h2><a name="introduction">Introduction</a></h2>
 <!-- *********************************************************************** -->
 
 <div>
 
 <p>This document attempts to describe a few coding standards that are being used
 in the LLVM source tree.  Although no coding standards should be regarded as
-absolute requirements to be followed in all instances, coding standards can be
-useful.</p>
+absolute requirements to be followed in all instances, coding standards are
+particularly important for large-scale code bases that follow a library-based
+design (like LLVM).</p>
 
 <p>This document intentionally does not prescribe fixed standards for religious
 issues such as brace placement and space usage.  For issues like this, follow
@@ -103,14 +102,27 @@ the golden rule:</p>
 
 <blockquote>
 
-<p><b><a name="goldenrule">If you are adding a significant body of source to a
-project, feel free to use whatever style you are most comfortable with.  If you
-are extending, enhancing, or bug fixing already implemented code, use the style
-that is already being used so that the source is uniform and easy to
-follow.</a></b></p>
+<p><b><a name="goldenrule">If you are extending, enhancing, or bug fixing
+already implemented code, use the style that is already being used so that the
+source is uniform and easy to follow.</a></b></p>
 
 </blockquote>
+  
+<p>Note that some code bases (e.g. libc++) have really good reasons to deviate
+from the coding standards.  In the case of libc++, this is because the naming
+and other conventions are dictated by the C++ standard.  If you think there is
+a specific good reason to deviate from the standards here, please bring it up
+on the LLVMdev mailing list.</p>
 
+<p>There are some conventions that are not uniformly followed in the code base
+(e.g. the naming convention).  This is because they are relatively new, and a
+lot of code was written before they were put in place.  Our long term goal is
+for the entire codebase to follow the convention, but we explicitly <em>do 
+not</em> want patches that do large-scale reformating of existing code.  OTOH,
+it is reasonable to rename the methods of a class if you're about to change it
+in some other way.  Just do the reformating as a separate commit from the
+functionality change. </p>
+  
 <p>The ultimate goal of these guidelines is the increase readability and
 maintainability of our common source base. If you have suggestions for topics to
 be included, please mail them to <a
@@ -141,11 +153,11 @@ href="mailto:sabre@nondot.org">Chris</a>.</p>
 <div>
 
 <p>Comments are one critical part of readability and maintainability.  Everyone
-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>
+knows they should comment their code, and so should you.  When writing comments,
+write them as English prose, which means they should use proper capitalization,
+punctuation, etc.  Aim to describe what a code is trying to do and why, not
+"how" it does it at a micro level. Here are a few critical things to
+document:</p>
 
 <h5>File Headers</h5>
 
@@ -153,9 +165,7 @@ documentation is very useful:</p>
 
 <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>
+checked into the tree.  The standard header looks like this:</p>
 
 <div class="doc_code">
 <pre>
@@ -198,9 +208,8 @@ included, as well as any notes or "gotchas" in the code to watch out for.</p>
 
 <p>Classes are one fundamental part of a good object oriented design.  As such,
 a class definition should have a comment block that explains what the class is
-used for... if it's not obvious.  If it's so completely obvious your grandma
-could figure it out, it's probably safe to leave it out.  Naming classes
-something sane goes a long ways towards avoiding writing documentation.</p>
+used for and how it works.  Every non-trivial class is expected to have a
+doxygen comment block.</p>
 
 
 <h5>Method information</h5>
@@ -211,8 +220,7 @@ something sane goes a long ways towards avoiding writing documentation.</p>
 documented properly.  A quick note about what it does and a description of the
 borderline behaviour is all that is necessary here (unless something
 particularly tricky or insidious is going on).  The hope is that people can
-figure out how to use your interfaces without reading the code itself... that is
-the goal metric.</p>
+figure out how to use your interfaces without reading the code itself.</p>
 
 <p>Good things to talk about here are what happens when something unexpected
 happens: does the method return null?  Abort?  Format your hard disk?</p>
@@ -398,14 +406,6 @@ if ((V = getValue())) {
 <p>which shuts <tt>gcc</tt> up.  Any <tt>gcc</tt> warning that annoys you can
 be fixed by massaging the code appropriately.</p>
 
-<p>These are the <tt>gcc</tt> warnings that I prefer to enable:</p>
-
-<div class="doc_code">
-<pre>
--Wall -Winline -W -Wwrite-strings -Wno-unused
-</pre>
-</div>
-
 </div>
 
 <!-- _______________________________________________________________________ -->