Fix some links to C++11 feature papers in the Coding Standards

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

diff --git a/docs/CodingStandards.rst b/docs/CodingStandards.rst
index 90835307b15ce3c3ca7a4d7a39b7e7fc5f0e6604..9aefa247e9ce537258707391f71b198227ee0c0f 100644 (file)
--- a/docs/CodingStandards.rst
+++ b/docs/CodingStandards.rst
@@ -1,5 +1,3 @@
-.. _coding_standards:
-

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


@@ -16,9 +14,9 @@ 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).
 
 particularly important for large-scale code bases that follow a library-based
 design (like LLVM).
 

-This document intentionally does not prescribe fixed standards for religious
-issues such as brace placement and space usage.  For issues like this, follow
-the golden rule:
+While this document may provide guidance for some mechanical formatting issues,
+whitespace, or other "microscopic details", these are not fixed standards.
+Always follow the golden rule:

 
 .. _Golden Rule:
 
 
 .. _Golden Rule:
 


@@ -45,6 +43,121 @@ 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 `Chris <mailto:sabre@nondot.org>`_.
 
 maintainability of our common source base. If you have suggestions for topics to
 be included, please mail them to `Chris <mailto:sabre@nondot.org>`_.
 

+Languages, Libraries, and Standards
+===================================
+
+Most source code in LLVM and other LLVM projects using these coding standards
+is C++ code. There are some places where C code is used either due to
+environment restrictions, historical restrictions, or due to third-party source
+code imported into the tree. Generally, our preference is for standards
+conforming, modern, and portable C++ code as the implementation language of
+choice.
+
+C++ Standard Versions
+---------------------
+
+LLVM and Clang are currently written using C++98/03 conforming code, with
+selective use of C++11 features when they are present in the toolchain.
+Projects like LLD and LLDB are already heavily using C++11 features.
+
+However, LLVM and Clange are also in the process of switching to use C++11 as
+the base line for standards conformance. Once completed, the same standard
+baseline will be used for LLVM, Clang, and LLD. LLDB is pushing forward much
+more aggressively and has their own baseline.
+
+C++ Standard Library
+--------------------
+
+Use the C++ standard library facilities whenever they are available for
+a particular task. LLVM and related projects emphasize and rely on the standard
+library facilities for as much as possible. Common support libraries providing
+functionality missing from the standard library for which there are standard
+interfaces or active work on adding standard interfaces will often be
+implemented in the LLVM namespace following the expected standard interface.
+
+There are some exceptions such as the standard I/O streams library which are
+avoided. Also, there is much more detailed information on these subjects in the
+`Programmer's Manual`_.
+
+.. _Programmer's Manual:
+  http://llvm.org/docs/ProgrammersManual.html
+
+Supported C++11 Language and Library Features
+-------------------------------------------
+
+.. warning::
+  This section is written to reflect the expected state **AFTER** the
+  transition to C++11 is complete for the LLVM source tree.
+
+While LLVM, Clang, and LLD use C++11, not all features are available in all of
+the toolchains which we support. The set of features supported for use in LLVM
+is the intersection of those supported in MSVC 2012, GCC 4.7, and Clang 3.1.
+The ultimate definition of this set is what build bots with those respective
+toolchains accept. Don't argue with the build bots.
+
+Each toolchain provides a good reference for what it accepts:
+* Clang: http://clang.llvm.org/cxx_status.html
+* GCC: http://gcc.gnu.org/projects/cxx0x.html
+* MSVC: http://msdn.microsoft.com/en-us/library/hh567368.aspx
+
+In most cases, the MSVC list will be the dominating factor. Here is a summary
+of the features that are expected to work. Features not on this list are
+unlikely to be supported by our host compilers.
+
+* Rvalue references: N2118_
+  * But *not* Rvalue references for ``*this`` or member qualifiers (N2439_)
+* Static assert: N1720_
+* ``auto`` type deduction: N1984_, N1737_
+* Trailing return types: N2541_
+* Lambdas: N2927_
+* ``decltype``: N2343_
+* Nested closing right angle brackets: N1757_
+* Extern templates: N1987_
+* ``nullptr``: N2431_
+* Strongly-typed and forward declarable enums: N2347_, N2764_
+* Local and unnamed types as template arguments: N2657_
+* Range-based for-loop: N2930_
+* ``override`` and ``final``: N2928_, N3206_, N3272_
+* Atomic operations and the C++11 memory model: N2429_
+
+.. _N2118: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2118.html
+.. _N2439: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2439.htm
+.. _N1720: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2004/n1720.html
+.. _N1984: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1984.pdf
+.. _N1737: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2004/n1737.pdf
+.. _N2541: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2541.htm
+.. _N2927: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2009/n2927.pdf
+.. _N2343: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2343.pdf
+.. _N1757: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1757.html
+.. _N1987: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1987.htm
+.. _N2431: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2431.pdf
+.. _N2347: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2347.pdf
+.. _N2764: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2764.pdf
+.. _N2657: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2657.htm
+.. _N2930: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2009/n2930.html
+.. _N2928: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2009/n2928.htm
+.. _N3206: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3206.htm
+.. _N3272: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2011/n3272.htm
+.. _N2429: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2429.htm
+
+The supported features in the C++11 standard libraries are less well tracked,
+but also much greater. Most of the standard libraries implement most of C++11's
+library. The most likely lowest common denominator is Linux support. For
+libc++, the support is just poorly tested and undocumented but expected to be
+largely complete. YMMV. For libstdc++, the support is documented in detail in
+`the libstdc++ manual`_. There are some very minor missing facilities that are
+unlikely to be common problems, and there are a few larger gaps that are worth
+being aware of:
+
+* Not all of the type traits are implemented
+* No regular expression library.
+* While most of the atomics library is well implemented, the fences are
+  missing. Fortunately, they are rarely needed.
+* The locale support is incomplete.
+
+.. _the libstdc++ manual:
+  http://gcc.gnu.org/onlinedocs/gcc-4.7.3/libstdc++/manual/manual/status.html#status.iso.2011
+

 Mechanical Source Issues
 ========================
 
 Mechanical Source Issues
 ========================
 


@@ -284,17 +397,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


@@ -409,7 +515,8 @@ code.
 
 That said, LLVM does make extensive use of a hand-rolled form of RTTI that use
 templates like `isa<>, cast<>, and dyn_cast<> <ProgrammersManual.html#isa>`_.
 
 That said, LLVM does make extensive use of a hand-rolled form of RTTI that use
 templates like `isa<>, cast<>, and dyn_cast<> <ProgrammersManual.html#isa>`_.

-This form of RTTI is opt-in and can be added to any class.  It is also
+This form of RTTI is opt-in and can be
+:doc:`added to any class <HowToSetUpLLVMStyleRTTI>`. It is also

 substantially more efficient than ``dynamic_cast<>``.
 
 .. _static constructor:
 substantially more efficient than ``dynamic_cast<>``.
 
 .. _static constructor:


@@ -713,8 +820,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;
     }


@@ -732,8 +839,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;
   }


@@ -804,7 +911,9 @@ In general, names should be in camel case (e.g. ``TextFileReader`` and
   
 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. ``begin()``,
   
 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. ``begin()``,

-``push_back()``, and ``empty()``).
+``push_back()``, and ``empty()``). Classes that provide multiple
+iterators should add a singular prefix to ``begin()`` and ``end()``
+(e.g. ``global_begin()`` and ``use_begin()``).

 
 Here are some examples of good and bad names:
 
 
 Here are some examples of good and bad names:
 


@@ -820,8 +929,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.

     ...
   }
 
     ...
   }
 


@@ -841,16 +950,16 @@ 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:
 
 .. code-block:: c++
 
   }
 
 Here are more examples:
 
 .. code-block:: c++
 

-  assert(Ty->isPointerType() && "Can't allocate a non pointer type!");
+  assert(Ty->isPointerType() && "Can't allocate a non-pointer type!");

 
   assert((Opcode == Shl || Opcode == Shr) && "ShiftInst Opcode invalid!");
 
 
   assert((Opcode == Shl || Opcode == Shr) && "ShiftInst Opcode invalid!");
 


@@ -1035,7 +1144,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.
 


@@ -1096,6 +1205,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
 -------------------
 


@@ -1111,27 +1248,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


@@ -1139,11 +1276,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.


@@ -1168,46 +1305,10 @@ Namespace Indentation
 
 In general, we strive to reduce indentation wherever possible.  This is useful
 because we want code to `fit into 80 columns`_ without wrapping horribly, but
 
 In general, we strive to reduce indentation wherever possible.  This is useful
 because we want code to `fit into 80 columns`_ without wrapping horribly, but

-also because it makes it easier to understand the code.  Namespaces are a funny
-thing: they are often large, and we often desire to put lots of stuff into them
-(so they can be large).  Other times they are tiny, because they just hold an
-enum or something similar.  In order to balance this, we use different
-approaches for small versus large namespaces.
-
-If a namespace definition is small and *easily* fits on a screen (say, less than
-35 lines of code), then you should indent its body.  Here's an example:
-
-.. code-block:: c++
-
-  namespace llvm {
-    namespace X86 {
-      /// \brief An enum for the x86 relocation codes.  Note that
-      /// the terminology here doesn't follow x86 convention - word means
-      /// 32-bit and dword means 64-bit.
-      enum RelocationType {
-        /// \brief PC relative relocation, add the relocated value to
-        /// the value already in memory, after we adjust it for where the PC is.
-        reloc_pcrel_word = 0,
-
-        /// \brief PIC base relative relocation, add the relocated value to
-        /// the value already in memory, after we adjust it for where the
-        /// PIC base is.
-        reloc_picrel_word = 1,
-
-        /// \brief Absolute relocation, just add the relocated value to the
-        /// value already in memory.
-        reloc_absolute_word = 2,
-        reloc_absolute_dword = 3
-      };
-    }
-  }
-
-Since the body is small, indenting adds value because it makes it very clear
-where the namespace starts and ends, and it is easy to take the whole thing in
-in one "gulp" when reading the code.  If the blob of code in the namespace is
-larger (as it typically is in a header in the ``llvm`` or ``clang`` namespaces),
-do not indent the code, and add a comment indicating what namespace is being
-closed.  For example:
+also because it makes it easier to understand the code. To facilitate this and
+avoid some insanely deep nesting on occasion, don't indent namespaces. If it
+helps readability, feel free to add a comment indicating what namespace is
+being closed by a ``}``.  For example:

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


@@ -1229,12 +1330,12 @@ closed.  For example:
   } // end namespace knowledge
   } // end namespace llvm
 
   } // end namespace knowledge
   } // end namespace llvm
 

-Because the class is large, we don't expect that the reader can easily
-understand the entire concept in a glance, and the end of the file (where the
-namespaces end) may be a long ways away from the place they open.  As such,
-indenting the contents of the namespace doesn't add any value, and detracts from
-the readability of the class.  In these cases it is best to *not* indent the
-contents of the namespace.
+
+Feel free to skip the closing comment when the namespace being closed is
+obvious for any reason. For example, the outer-most namespace in a header file
+is rarely a source of confusion. But namespaces both anonymous and named in
+source files that are being closed half way through the file probably could use
+clarification.

 
 .. _static:
 
 
 .. _static:
 


@@ -1263,12 +1364,12 @@ good:
 .. code-block:: c++
 
   namespace {
 .. code-block:: c++
 
   namespace {

-    class StringSort {
-    ...
-    public:
-      StringSort(...)
-      bool operator<(const char *RHS) const;
-    };
+  class StringSort {
+  ...
+  public:
+    StringSort(...)
+    bool operator<(const char *RHS) const;
+  };

   } // end anonymous namespace
 
   static void runHelper() { 
   } // end anonymous namespace
 
   static void runHelper() { 


@@ -1284,6 +1385,7 @@ This is bad:
 .. code-block:: c++
 
   namespace {
 .. code-block:: c++
 
   namespace {

+

   class StringSort {
   ...
   public:
   class StringSort {
   ...
   public:


@@ -1310,7 +1412,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++