restructure this for readability, correct the example to follow the public ivar name convention

llvm-svn: 121443

docs/CodingStandards.html

@@ -814,32 +814,46 @@ locality.</p>
 </div>
 
 <div class="doc_text">
-<p>Poorly-chosen names mislead the reader and cause bugs.  We cannot
+<p>Poorly-chosen names can mislead the reader and cause bugs. We cannot
 stress enough how important it is to use <em>descriptive</em> names.
 Pick names that match the semantics and role of the underlying
 entities, within reason.  Avoid abbreviations unless they are well
-known.</p>
+known.  After picking a good name, make sure to use consistent capitalization
+for the name, as inconsistency requires clients to either memorize the APIs or
+to look it up to find the exact spelling.
+</p>
 
-<p>In general, names of types, functions, variables, and enumerators
-should be in camel case (e.g. <tt>TextFileReader</tt>
-and <tt>isLValue()</tt>).  Type names (including classes, structs,
-enums, typedefs, etc) should be nouns and start with an upper-case
-letter (e.g. <tt>TextFileReader</tt>).  An <tt>enum</tt> for all the
-different kinds of something should be named with the <tt>Kind</tt>
-suffix.  Function names should be verb phrases (as they represent
-actions) and start with a lower-case letter (e.g. a predicate may be
-named <tt>isFoo()</tt> or <tt>hasBar()</tt>, while the name of a
-command-like function should be imperative,
-like <tt>openFile()</tt>).</p>
+<p>In general, names should be in camel case (e.g. <tt>TextFileReader</tt>
+and <tt>isLValue()</tt>).  Different kinds of declarations have different rules:
+</p>
 
-<p>Enumerators and public member variables should start with an
-upper-case letter, just like types.  Unless the enumerators are
-defined in their own small namespace or inside a class, they should
-have a prefix.  For example, <tt>enum ValueKind { ... };</tt> may
-contain enumerators like
-<tt>VK_Argument</tt>, <tt>VK_BasicBlock</tt>, etc.  Enumerators that
-are just convenience constants are exempt from the requirement for a
-prefix.  For instance:</p>
+<ul>
+<li><b>Type names</b> (including classes, structs, enums, typedefs, etc) should
+    be nouns and start with an upper-case letter (e.g. <tt>TextFileReader</tt>).
+</li>
+  
+<li><b>Function names</b> should be verb phrases (as they represent
+    actions), and command-like function should be imperative.  The name should
+    be camel case, and start with a lower case letter (e.g. <tt>openFile()</tt>
+    or <tt>isFoo()</tt>).
+</li>
+
+<li><b>Enum declarations</b> (e.g. "enum Foo {...}") are types, so they should
+  follow the naming conventions for types.  A common use for enums is as a
+  discriminator for a union, or an indicator of a subclass.  When an enum is
+  used for something like this, it should have a "Kind" suffix (e.g.
+  "ValueKind").
+</li>
+  
+<li><b>Enumerators</b> (e.g. enum { Foo, Bar }) and 
+<b>public member variables</b> should start with an upper-case letter, just
+like types.   Unless the enumerators are defined in their own small
+namespace or inside a class, enumerators should have a prefix corresponding
+to the enum declaration name.  For example, <tt>enum ValueKind { ... };</tt>
+may contain enumerators like <tt>VK_Argument</tt>, <tt>VK_BasicBlock</tt>,
+etc.  Enumerators that are just convenience constants are exempt from the
+requirement for a prefix.  For instance:</p>
+  
 <div class="doc_code">
 <pre>
 enum {
@@ -849,6 +863,10 @@ enum {
 </pre>
 </div>
 
+</li>
+</ul>
+  
+
 <p>As an exception, classes that mimic STL classes can have member names
 in STL's style of lower-case words separated by underscores
 (e.g. <tt>begin()</tt>, <tt>push_back()</tt>, and <tt>empty()</tt>).</p>
@@ -858,16 +876,16 @@ in STL's style of lower-case words separated by underscores
 <pre>
 class VehicleMaker {
   ...
-  Factory&lt;Tire&gt; f;            // Bad -- abbreviation and non-descriptive.
-  Factory&lt;Tire&gt; factory;      // Better.
-  Factory&lt;Tire&gt; tireFactory;  // Even better -- if VehicleMaker has more than one
+  Factory&lt;Tire&gt; F;            // Bad -- abbreviation and non-descriptive.
+  Factory&lt;Tire&gt; Factory;      // Better.
+  Factory&lt;Tire&gt; TireFactory;  // Even better -- if VehicleMaker has more than one
                               // kind of factories.
 };
 
 Vehicle MakeVehicle(VehicleType Type) {
-  VehicleMaker m;  // Might be OK if having a short life-span.
-  Tire tmp1 = m.makeTire();  // Bad -- 'tmp1' provides no information.
-  Light headlight = m.makeLight("head");  // Good -- descriptive.
+  VehicleMaker M;                     // Might be OK if having a short life-span.
+  Tire tmp1 = M.makeTire();  // Bad -- 'tmp1' provides no information.
+  Light headlight = M.makeLight("head");  // Good -- descriptive.
   ...
 }
 </pre>