From 055899b12c1ea0f9816e13335568644f90fd6770 Mon Sep 17 00:00:00 2001 From: Johannes Doerfert Date: Mon, 10 Feb 2020 11:07:14 -0600 Subject: [PATCH] [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 --- docs/CodingStandards.rst | 28 ++++++++++++++++++---------- 1 file changed, 18 insertions(+), 10 deletions(-) diff --git a/docs/CodingStandards.rst b/docs/CodingStandards.rst index 394b1c602e0..4cf6c726c53 100644 --- a/docs/CodingStandards.rst +++ b/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 `_) -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 ----------------------