[CodingStandards] Clarify C++ Standard Library usage

[jdoerfert]

Summary

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

[rjmccall]

I think I would prefer if this were a somewhat less absolute statement, like:

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.

[rjmccall]

In D74340#1867595, @rjmccall wrote:

I think I would prefer if this were a somewhat less absolute statement, like:

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.

Actually, do we have a discussion of the trade-offs between collection
implementations anywhere? Some of that could go in header comments,
but it might make more sense to have a place in the documentation;
among other things, it'd be a way of pointing people towards the really
specialized implementations (like llvm::TinyPtrVector) that otherwise
they might have a hard time finding.

[jdoerfert]

In D74340#1867595, @rjmccall wrote:

I think I would prefer if this were a somewhat less absolute statement, like:

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.

Instead of

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`.

?

it'd be a way of pointing people towards the really specialized implementations

A list of all "specialized" versions of a common data structure would be nice, with trade-offs or use cases.
We could link to that from here once it exists.

[rjmccall]

In D74340#1867850, @jdoerfert wrote:

In D74340#1867595, @rjmccall wrote:

I think I would prefer if this were a somewhat less absolute statement, like:

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.

Instead of

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`.

?

That's what I was thinking. What do you think?

it'd be a way of pointing people towards the really specialized implementations

A list of all "specialized" versions of a common data structure would be nice, with trade-offs or use cases.
We could link to that from here once it exists.

Any interest on putting that together? :)

[jdoerfert]

Use wording provided by @rjmccall

[jdoerfert]

In D74340#1867854, @rjmccall wrote:

Any interest on putting that together? :)

Maybe but not right now. I'd be interested in reading it to discover new things ;)

I think your wording is good, I updated the text.

[jdoerfert]

Use ` not

[rjmccall]

llvm/docs/CodingStandards.rst

73–77

There should be a comma after "structures" here.

Feel free to commit with that fix.

[jdoerfert]

@rjmccall :

Feel free to commit with that fix.

For the record, I take that as an accept and commit this.

[fhahn]

llvm/docs/CodingStandards.rst

85

The programmer's manual has a section Picking the Right Data Structure for a Task https://llvm.org/docs/ProgrammersManual.html#picking-the-right-data-structure-for-a-task

It goes into much more detail, but it might be good to link/unify both?

[rjmccall]

llvm/docs/CodingStandards.rst

85

Ah, I'd forgotten about that section completely. Yes, it should absolutely be linked here. I don't think we want to merge the sections, though; what we've got now is a fine lead-in to a link like "For more information about LLVM's data structures and the tradeoffs they make, please consult that section of the programmer's manual."

[jdoerfert]

Done b0279d62ac68837bc58393a81518a2c5b4ca6163

llvm/docs/CodingStandards.rst

 * Clang: https://clang.llvm.org/cxx_status.html
 * GCC: https://gcc.gnu.org/projects/cxx-status.html#cxx14
 * MSVC: https://msdn.microsoft.com/en-us/library/hh567368.aspx
 
 
 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
 ----------------------
 
 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.