diff --git a/llvm/docs/CodingStandards.rst b/llvm/docs/CodingStandards.rst --- a/llvm/docs/CodingStandards.rst +++ b/llvm/docs/CodingStandards.rst @@ -762,6 +762,49 @@ 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