[llvm] 236fcbc - Add coding standard recommending use of qualifiers in cpp files

[Reid Kleckner via llvm-commits]

Author: Reid Kleckner
Date: 2020-02-18T14:08:56-08:00
New Revision: 236fcbc21a7a88724240e818653fbb328a24bfbb

URL: https://github.com/llvm/llvm-project/commit/236fcbc21a7a88724240e818653fbb328a24bfbb
DIFF: https://github.com/llvm/llvm-project/commit/236fcbc21a7a88724240e818653fbb328a24bfbb.diff

LOG: Add coding standard recommending use of qualifiers in cpp files

There is prior art for this in the code base itself, and a recent
example of this here: c45f8d49897f

This came up in discussion on this review where @maskray was going the
opposite direction:
  https://reviews.llvm.org/D68772

Given that there is disagreement, we should make a choice and document
it.

Thanks to John McCall for the precise wording.

Reviewed By: MaskRay, rjmccall

Differential Revision: https://reviews.llvm.org/D74515

Added: 
    

Modified: 
    llvm/docs/CodingStandards.rst

Removed: 
    


################################################################################
diff  --git a/llvm/docs/CodingStandards.rst b/llvm/docs/CodingStandards.rst
index 2ade20b01c1d..0e9bd8535b76 100644
--- a/llvm/docs/CodingStandards.rst
+++ b/llvm/docs/CodingStandards.rst
@@ -762,6 +762,49 @@ your private interface remains private and undisturbed by outsiders.
     It's okay to put extra implementation methods in a public class itself. Just
     make them private (or protected) and all is well.
 
+Use Namespace Qualifiers to Implement Previously Declared Functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When providing an out of line implementation of a function in a source file, do
+not open namespace blocks in the source file. Instead, use namespace qualifiers
+to help ensure that your definition matches an existing declaration. Do this:
+
+.. code-block:: c++
+
+  // Foo.h
+  namespace llvm {
+  int foo(const char *s);
+  }
+
+  // Foo.cpp
+  #include "Foo.h"
+  using namespace llvm;
+  int llvm::foo(const char *s) {
+    // ...
+  }
+
+Doing this helps to avoid bugs where the definition does not match the
+declaration from the header. For example, the following C++ code defines a new
+overload of ``llvm::foo`` instead of providing a definition for the existing
+function declared in the header:
+
+.. code-block:: c++
+
+  // Foo.cpp
+  #include "Foo.h"
+  namespace llvm {
+  int foo(char *s) { // Mismatch between "const char *" and "char *"
+  }
+  } // end namespace llvm
+
+This error will not be caught until the build is nearly complete, when the
+linker fails to find a definition for any uses of the original function.  If the
+function were instead defined with a namespace qualifier, the error would have
+been caught immediately when the definition was compiled.
+
+Class method implementations must already name the class and new overloads
+cannot be introduced out of line, so this recommendation does not apply to them.
+
 .. _early exits:
 
 Use Early Exits and ``continue`` to Simplify Code