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,47 @@ It's okay to put extra implementation methods in a public class itself. Just make them private (or protected) and all is well. +Use Name 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) { + // ... + } + +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::foo``, for +example: + +.. code-block:: c++ + + // Foo.cpp + #include "Foo.h" + namespace llvm { + int foo(char *s) { // Mismatch between "const char *" and "char *" + } + } // end namespace llvm + +It is more likely that the programmer intended to implement +``llvm::foo(const char *)`` in this case. + +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