[PATCH] D74340: [CodingStandards] Clarify C++ Standard Library usage

[Johannes Doerfert via Phabricator via llvm-commits]

jdoerfert created this revision.
jdoerfert added reviewers: hfinkel, tstellar, echristo, chandlerc, xbolva00, spatel, arsenm, lebedev.ri, fhahn, nlopes, reames, regehr, efriedma, rjmccall, rsmith.
Herald added subscribers: bollu, wdng.
Herald added a project: LLVM.

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


Repository:
  rG LLVM Github Monorepo

https://reviews.llvm.org/D74340

Files:
  llvm/docs/CodingStandards.rst


Index: llvm/docs/CodingStandards.rst
===================================================================
--- llvm/docs/CodingStandards.rst
+++ llvm/docs/CodingStandards.rst
@@ -70,19 +70,24 @@
 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. It is generally
+preferable to use the LLVM support libraries over the C++ standard library
+version, especially if any of the specializations is expected to improve
+performance, e.g., `SmallVector` vs `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
 ----------------------


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D74340.243593.patch
Type: text/x-patch
Size: 1973 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20200210/7ea51214/attachment.bin>