Merge these tests.

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

diff --git a/docs/CodingStandards.rst b/docs/CodingStandards.rst
index c89a30d8eeb555df182cca3dd7129be10b8c644e..4d66ad75743541f3baeaa2cdd6bef251517c61c5 100644 (file)
--- a/docs/CodingStandards.rst
+++ b/docs/CodingStandards.rst
@@ -1,5 +1,3 @@
-.. _coding_standards:
-

 =====================
 LLVM Coding Standards
 =====================
 =====================
 LLVM Coding Standards
 =====================


@@ -284,17 +282,10 @@ listed.  We prefer these ``#include``\s to be listed in this order:
 
 #. Main Module Header
 #. Local/Private Headers
 
 #. Main Module Header
 #. Local/Private Headers

-#. ``llvm/*``
-#. ``llvm/Analysis/*``
-#. ``llvm/Assembly/*``
-#. ``llvm/Bitcode/*``
-#. ``llvm/CodeGen/*``
-#. ...
-#. ``llvm/Support/*``
-#. ``llvm/Config/*``
+#. ``llvm/...``

 #. System ``#include``\s
 
 #. System ``#include``\s
 

-and each category should be sorted by name.
+and each category should be sorted lexicographically by the full path.

 
 The `Main Module Header`_ file applies to ``.cpp`` files which implement an
 interface defined by a ``.h`` file.  This ``#include`` should always be included
 
 The `Main Module Header`_ file applies to ``.cpp`` files which implement an
 interface defined by a ``.h`` file.  This ``#include`` should always be included


@@ -714,8 +705,8 @@ sort of thing is:
 .. code-block:: c++
 
   bool FoundFoo = false;
 .. code-block:: c++
 
   bool FoundFoo = false;

-  for (unsigned i = 0, e = BarList.size(); i != e; ++i)
-    if (BarList[i]->isFoo()) {
+  for (unsigned I = 0, E = BarList.size(); I != E; ++I)
+    if (BarList[I]->isFoo()) {

       FoundFoo = true;
       break;
     }
       FoundFoo = true;
       break;
     }


@@ -733,8 +724,8 @@ code to be structured like this:
 
   /// \returns true if the specified list has an element that is a foo.
   static bool containsFoo(const std::vector<Bar*> &List) {
 
   /// \returns true if the specified list has an element that is a foo.
   static bool containsFoo(const std::vector<Bar*> &List) {

-    for (unsigned i = 0, e = List.size(); i != e; ++i)
-      if (List[i]->isFoo())
+    for (unsigned I = 0, E = List.size(); I != E; ++I)
+      if (List[I]->isFoo())

         return true;
     return false;
   }
         return true;
     return false;
   }


@@ -821,8 +812,8 @@ Here are some examples of good and bad names:
 
   Vehicle MakeVehicle(VehicleType Type) {
     VehicleMaker M;                         // Might be OK if having a short life-span.
 
   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.
+    Tire Tmp1 = M.makeTire();               // Bad -- 'Tmp1' provides no information.
+    Light Headlight = M.makeLight("head");  // Good -- descriptive.

     ...
   }
 
     ...
   }
 


@@ -842,9 +833,9 @@ enforced, and hopefully what to do about it.  Here is one complete example:
 
 .. code-block:: c++
 
 
 .. code-block:: c++
 

-  inline Value *getOperand(unsigned i) { 
-    assert(i < Operands.size() && "getOperand() out of range!");
-    return Operands[i]; 
+  inline Value *getOperand(unsigned I) {
+    assert(I < Operands.size() && "getOperand() out of range!");
+    return Operands[I];

   }
 
 Here are more examples:
   }
 
 Here are more examples:


@@ -1036,7 +1027,7 @@ 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
 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: "``SomeMap[x]->end()``" and map lookups
+expression was actually something like: "``SomeMap[X]->end()``" 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.
 
 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.
 


@@ -1097,6 +1088,34 @@ flushes the output stream.  In other words, these are equivalent:
 Most of the time, you probably have no reason to flush the output stream, so
 it's better to use a literal ``'\n'``.
 
 Most of the time, you probably have no reason to flush the output stream, so
 it's better to use a literal ``'\n'``.
 

+Don't use ``inline`` when defining a function in a class definition
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A member function defined in a class definition is implicitly inline, so don't
+put the ``inline`` keyword in this case.
+
+Don't:
+
+.. code-block:: c++
+
+  class Foo {
+  public:
+    inline void bar() {
+      // ...
+    }
+  };
+
+Do:
+
+.. code-block:: c++
+
+  class Foo {
+  public:
+    void bar() {
+      // ...
+    }
+  };
+

 Microscopic Details
 -------------------
 
 Microscopic Details
 -------------------
 


@@ -1112,27 +1131,27 @@ macros.  For example, this is good:
 
 .. code-block:: c++
 
 
 .. code-block:: c++
 

-  if (x) ...
-  for (i = 0; i != 100; ++i) ...
-  while (llvm_rocks) ...
+  if (X) ...
+  for (I = 0; I != 100; ++I) ...
+  while (LLVMRocks) ...

 
   somefunc(42);
   assert(3 != 4 && "laws of math are failing me");
   
 
   somefunc(42);
   assert(3 != 4 && "laws of math are failing me");
   

-  a = foo(42, 92) + bar(x);
+  A = foo(42, 92) + bar(X);

 
 and this is bad:
 
 .. code-block:: c++
 
 
 and this is bad:
 
 .. code-block:: c++
 

-  if(x) ...
-  for(i = 0; i != 100; ++i) ...
-  while(llvm_rocks) ...
+  if(X) ...
+  for(I = 0; I != 100; ++I) ...
+  while(LLVMRocks) ...

 
   somefunc (42);
   assert (3 != 4 && "laws of math are failing me");
   
 
   somefunc (42);
   assert (3 != 4 && "laws of math are failing me");
   

-  a = foo (42, 92) + bar (x);
+  A = foo (42, 92) + bar (X);

 
 The reason for doing this is not completely arbitrary.  This style makes control
 flow operators stand out more, and makes expressions flow better. The function
 
 The reason for doing this is not completely arbitrary.  This style makes control
 flow operators stand out more, and makes expressions flow better. The function


@@ -1140,11 +1159,11 @@ call operator binds very tightly as a postfix operator.  Putting a space after a
 function name (as in the last example) makes it appear that the code might bind
 the arguments of the left-hand-side of a binary operator with the argument list
 of a function and the name of the right side.  More specifically, it is easy to
 function name (as in the last example) makes it appear that the code might bind
 the arguments of the left-hand-side of a binary operator with the argument list
 of a function and the name of the right side.  More specifically, it is easy to

-misread the "``a``" example as:
+misread the "``A``" example as:

 
 .. code-block:: c++
 
 
 .. code-block:: c++
 

-  a = foo ((42, 92) + bar) (x);
+  A = foo ((42, 92) + bar) (X);

 
 when skimming through the code.  By avoiding a space in a function, we avoid
 this misinterpretation.
 
 when skimming through the code.  By avoiding a space in a function, we avoid
 this misinterpretation.


@@ -1311,7 +1330,7 @@ namespace just because it was declared there.
 See Also
 ========
 
 See Also
 ========
 

-A lot of these comments and recommendations have been culled for other sources.
+A lot of these comments and recommendations have been culled from other sources.

 Two particularly important books for our work are:
 
 #. `Effective C++
 Two particularly important books for our work are:
 
 #. `Effective C++