Add coding standard recommending use of qualifiers in cpp files

[rnk]

Summary

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.

My wording could probably use improvement, but I figured I'd send this
out anyway to see if people are receptive to the guideline.

[jlebar]

Do we have any nontrivially-long namespaces in LLVM?

[rjmccall]

I strongly agree with the substance of this recommendation.

This section would be a lot shorter and sweeter if you dropped (1) the mentions of methods and (2) the Foo type from the example. You can just make the overloads char * vs. const char * or something.

[rjmccall]

In D74515#1873345, @jlebar wrote:

Do we have any nontrivially-long namespaces in LLVM?

I don't think any of LLVM's top-level namespaces are more than 5 characters or so. Sometimes we have long nested namespaces to e.g. move the helper types/functions of a particular data structure out of llvm::, like with llvm::ilist_detail, but they're rare and generally local to a single file.

Some of our project libraries use nested namespaces, and the qualifiers all together can get pretty long, but that's not a problem for this recommendatiion because you can just use the interior namespace in the out-of-line definition:

using namespace clang;
using namespace CodeGen;

void CodeGen::foo() {...}

[rnk]

• shorten example

[rjmccall]

llvm/docs/CodingStandards.rst

789

Consider this:

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:

<example>

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.

[rnk]

llvm/docs/CodingStandards.rst

787

Bleh, this somehow got mangled while editing. :( Anyway, thanks for the precise wording, I'll use it.

[rnk]

• John writes very clearly, so use his recommended wording.

[MaskRay]

LG, but I'll defer to other reviewers who have been working on the project longer than me.

llvm/docs/CodingStandards.rst

 same directory as the source files, and include it locally.  This ensures that
 your private interface remains private and undisturbed by outsiders.
 
 .. note::
 
     It's okay to put extra implementation methods in a public class itself. Just
     make them private (or protected) and all is well.
 
+Open Namespaces in Header Files, Not Source Files
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To declare things in a namespace in a header file, open a namespace in the usual
+way:
+
+.. code-block:: c++
+
+  // Foo.h
+  namespace llvm {
+  class Foo {
+  public:
+    int foo();
+    // ...
+  };
+  int bar(Foo *p);
+  }
+
+When providing implementations in a source file for functions or methods
+declared in a header 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.cpp
+  #include "Foo.h"
+
+  using namespace llvm;
+
+  int Foo::foo() { /* ... */ }
+
+  int llvm::bar(Foo *p) {
+    // ...
+  }
+
+If every definition in the implementation file uses a previously declared
+qualifier, it helps to catch bugs where the definition does not match the
+declaration. In C++, this would declare a new overload of ``llvm::bar``, for
+example:
+
+.. code-block:: c++
+
+  // Foo.cpp
+  #include "Foo.h"
+
+  namespace llvm {
+  int bar(Bar *p) { // Note "Bar" does not match "Foo" above.
+  }
+  } // end namespace llvm
+
+It is more likely that the programmer intended to implement ``llvm::bar(Foo*)``
+in this case, but has not yet updated the prototype.
+
 .. _early exits:
 
 Use Early Exits and ``continue`` to Simplify Code
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 When reading code, keep in mind how much state and how many previous decisions
 have to be remembered by the reader to understand a block of code.  Aim to
 reduce indentation where possible when it doesn't make it more difficult to