[llvm] 5afd9fd - [CodingStandards] Clarify C++ Standard Library usage

[Johannes Doerfert via llvm-commits]

Author: Johannes Doerfert
Date: 2020-02-10T20:30:00-06:00
New Revision: 5afd9fd916beab15b8fe2e269b3c7466c9ffa574

URL: https://github.com/llvm/llvm-project/commit/5afd9fd916beab15b8fe2e269b3c7466c9ffa574
DIFF: https://github.com/llvm/llvm-project/commit/5afd9fd916beab15b8fe2e269b3c7466c9ffa574.diff

LOG: [CodingStandards] Clarify C++ Standard Library usage

The existing wording leaves it unclear if C++ standard library data
structures should be preferred over custom LLVM ones, e.g., SmallVector,
even though common practice seems clear on the issue. This change makes
the wording more explicit and aligns it better with the code base.

Some motivating statistics:

```
ag SmallVector llvm/lib/ | wc
  8846   40306  901421
 ag 'std::vector' llvm/lib/ | wc
  2123    8990  214482

ag SmallVector clang/lib/ | wc
  3023   13824  281691
ag 'std::vector' clang/lib/ | wc
   719    2914   72817
```

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

Added: 
    

Modified: 
    llvm/docs/CodingStandards.rst

Removed: 
    


################################################################################
diff  --git a/llvm/docs/CodingStandards.rst b/llvm/docs/CodingStandards.rst
index 394b1c602e05..4cf6c726c535 100644
--- a/llvm/docs/CodingStandards.rst
+++ b/llvm/docs/CodingStandards.rst
@@ -70,19 +70,27 @@ Each toolchain provides a good reference for what it accepts:
 C++ Standard Library
 --------------------
 
-Use the C++ standard library facilities whenever they are available for
-a particular task. LLVM and related projects emphasize and rely on the standard
-library facilities as much as possible.
-
-We avoid some standard facilities, like the I/O streams, and instead use LLVM's
-streams library (raw_ostream_). More detailed information on these subjects is
-available in the :doc:`ProgrammersManual`.
+Instead of implementing custom data structures, we encourage the use of C++
+standard library facilities or LLVM support libraries whenever they are
+available for a particular task. LLVM and related projects emphasize and rely
+on the standard library facilities and the LLVM support libraries as much as
+possible.
 
 LLVM support libraries (for example, `ADT
 <https://github.com/llvm/llvm-project/tree/master/llvm/include/llvm/ADT>`_)
-implement functionality missing in the standard library. Such libraries are
-usually implemented in the ``llvm`` namespace and follow the expected standard
-interface, when there is one.
+implement specialized data structures or functionality missing in the standard
+library. Such libraries are usually implemented in the ``llvm`` namespace and
+follow the expected standard interface, when there is one.
+
+When both C++ and the LLVM support libraries provide similar functionality, and
+there isn't a specific reason to favor the C++ implementation, it is generally
+preferable to use the LLVM library. For example, ``llvm::DenseMap`` should
+almost always be used instead of ``std::map`` or ``std::unordered_map``, and
+``llvm::SmallVector`` should usually be used instead of ``std::vector``.
+
+We explicitly avoid some standard facilities, like the I/O streams, and instead
+use LLVM's streams library (raw_ostream_). More detailed information on these
+subjects is available in the :doc:`ProgrammersManual`.
 
 Guidelines for Go code
 ----------------------