X-Git-Url: http://plrg.eecs.uci.edu/git/?a=blobdiff_plain;f=docs%2FCodingStandards.rst;h=0552c7117e2a89ef4c3104e7525f7268006de292;hb=ae39073d9917874d00c4f1a863b6f9c94679d144;hp=edf001aeda01f1908498754e6848cc46f7bcd89e;hpb=653638bea4c05fa3d68378d38a5feba60096287e;p=oota-llvm.git diff --git a/docs/CodingStandards.rst b/docs/CodingStandards.rst index edf001aeda0..0552c7117e2 100644 --- a/docs/CodingStandards.rst +++ b/docs/CodingStandards.rst @@ -76,10 +76,7 @@ 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 +:doc:`ProgrammersManual`. Supported C++11 Language and Library Features --------------------------------------------- @@ -109,6 +106,9 @@ unlikely to be supported by our host compilers. * ``auto`` type deduction: N1984_, N1737_ * Trailing return types: N2541_ * Lambdas: N2927_ + + * But *not* lambdas with default arguments. + * ``decltype``: N2343_ * Nested closing right angle brackets: N1757_ * Extern templates: N1987_ @@ -116,6 +116,11 @@ unlikely to be supported by our host compilers. * Strongly-typed and forward declarable enums: N2347_, N2764_ * Local and unnamed types as template arguments: N2657_ * Range-based for-loop: N2930_ + + * But ``{}`` are required around inner ``do {} while()`` loops. As a result, + ``{}`` are required around function-like macros inside range-based for + loops. + * ``override`` and ``final``: N2928_, N3206_, N3272_ * Atomic operations and the C++11 memory model: N2429_ @@ -138,6 +143,7 @@ unlikely to be supported by our host compilers. .. _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 +.. _MSVC-compatible RTTI: http://llvm.org/PR18951 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 @@ -153,6 +159,11 @@ being aware of: * While most of the atomics library is well implemented, the fences are missing. Fortunately, they are rarely needed. * The locale support is incomplete. +* ``std::initializer_list`` (and the constructors and functions that take it as + an argument) are not always available, so you cannot (for example) initialize + a ``std::vector`` with a braced initializer list. +* ``std::equal()`` (and other algorithms) incorrectly assert in MSVC when given + ``nullptr`` as an iterator. Other than these areas you should assume the standard library is available and working as expected until some build bot tells you otherwise. If you're in an @@ -165,6 +176,25 @@ traits header to emulate it. .. _the libstdc++ manual: http://gcc.gnu.org/onlinedocs/gcc-4.7.3/libstdc++/manual/manual/status.html#status.iso.2011 +Other Languages +--------------- + +Any code written in the Go programming language is not subject to the +formatting rules below. Instead, we adopt the formatting rules enforced by +the `gofmt`_ tool. + +Go code should strive to be idiomatic. Two good sets of guidelines for what +this means are `Effective Go`_ and `Go Code Review Comments`_. + +.. _gofmt: + https://golang.org/cmd/gofmt/ + +.. _Effective Go: + https://golang.org/doc/effective_go.html + +.. _Go Code Review Comments: + https://code.google.com/p/go-wiki/wiki/CodeReviewComments + Mechanical Source Issues ======================== @@ -598,7 +628,7 @@ is never used for a class. Because of this, we turn them off globally in the code. That said, LLVM does make extensive use of a hand-rolled form of RTTI that use -templates like `isa<>, cast<>, and dyn_cast<> `_. +templates like :ref:`isa\<>, cast\<>, and dyn_cast\<> `. This form of RTTI is opt-in and can be :doc:`added to any class `. It is also substantially more efficient than ``dynamic_cast<>``. @@ -732,6 +762,29 @@ type is already obvious from the context. Another time when ``auto`` works well for these purposes is when the type would have been abstracted away anyways, often behind a container's typedef such as ``std::vector::iterator``. +Beware unnecessary copies with ``auto`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The convenience of ``auto`` makes it easy to forget that its default behavior +is a copy. Particularly in range-based ``for`` loops, careless copies are +expensive. + +As a rule of thumb, use ``auto &`` unless you need to copy the result, and use +``auto *`` when copying pointers. + +.. code-block:: c++ + + // Typically there's no reason to copy. + for (const auto &Val : Container) { observe(Val); } + for (auto &Val : Container) { Val.change(); } + + // Remove the reference if you really want a new copy. + for (auto Val : Container) { Val.change(); saveSomewhere(Val); } + + // Copy pointers, but make it clear that they're pointers. + for (const auto *Ptr : Container) { observe(*Ptr); } + for (auto *Ptr : Container) { Ptr->change(); } + Style Issues ============ @@ -1251,9 +1304,9 @@ method will never be implemented. This enables other checks like ``-Wunused-private-field`` to run correctly on classes that contain these methods. -To maintain compatibility with C++03, ``LLVM_DELETED_FUNCTION`` should be used -which will expand to ``= delete`` if the compiler supports it. These methods -should still be declared private. Example of the uncopyable pattern: +For compatibility with MSVC, ``LLVM_DELETED_FUNCTION`` should be used which +will expand to ``= delete`` on compilers that support it. These methods should +still be declared private. Example of the uncopyable pattern: .. code-block:: c++