Make coding standards document more inclusive

[gribozavr]

Summary

Patch by Doug Gregor, Tres Popp, and Dmitri Gribenko.

[chandlerc]

A few minor further tweaks.

llvm/docs/CodingStandards.rst

56

Polly? Maybe its not important to list everything here.

Maybe this should say "Unless otherwise documented, LLVM subprojects are written ..."

60–61

"*Those* features are the intersection of *those* supported ..."

Maybe: "Nevertheless, we restrict ourselves to the intersection of features which are available..." and then "We describe our host compiler support in the GettingStarted page..."?

356

s/reasonably// ?

459

I think we can make this even better... Maybe:

"Compiler warnings are often useful and will help improve the code. Those that are not ..."

491–494

Delete the entire sentence from "These two language features ... is never used for a class.". I don't think it is phrased in an objective or good way IMO.

It might be possible to rephrase it, but honestly I don't think its that useful and so i'd also probable delete the subsequent sentence and keep going as far as needed. I don't think we need a lot of detailed discussion here.

[gribozavr]

Addressed review comments

llvm/docs/CodingStandards.rst

56

Changed to a blanket rule.

60–61

Changed to a parenthetical.

Nevertheless, we restrict ourselves to features which are available in the
major toolchains supported as host compilers (see :doc:GettingStarted page,
section Software).

356

Done.

459

Done.

491–494

Removed this sentence and other discussion of dynamic_cast.

[doug.gregor]

Can this get merged now?

[arsenm]

llvm/docs/CodingStandards.rst

87–88

New empty section?

[arsenm]

llvm/docs/CodingStandards.rst

87–88

Nevermind, the section below was renamed and mostly shifted out of the diff view

[bmcreusillet]

llvm/docs/CodingStandards.rst

79

There seem to be a spurious space in "func tionality"

Also the whole sentence is somewhat long, I would add commas for instance before "providing" and before "will often" to ease readability.

170

a object-oriented -> an object oriented?

184

I would turn this into: "for instance, does the method return null?", otherwise it may seem the only possibility.

294

The "In" does not seem consistent with the C example

308

same remark about "In"

426

A remark not related to the changes themselves:

"With C++11": Shouldn't it be "From C++11" or something similar?

505

This sentence does not appear to be properly linked to the preceding nor to the following one.

I feel a small explanation of the consequences in this sentence could be helpful. Also beginning the next sentence with "Moreover" or something appropriate.

508

s/have have/have/

557–558

Same remarks as before about the reference to C++11 ?

940

"we prefer" is repeated at a short interval. Maybe change the second one into "The code should instead be structured like this:"

[hfinkel]

llvm/docs/CodingStandards.rst

170

Should be:

an object-oriented design

(compound adjectives get a dash)

1354

control-flow operators

[gribozavr2]

llvm/docs/CodingStandards.rst

79

Thanks, removed the extra space and rewrote the sentence.

87–88

Marking as resolved.

170

s/a/an/ done.

184

Done.

294

Made them consistent.

308

Made them consistent.

426

Changed to "starting from c++11".

505

Added "making the code more difficult to reason about" to this sentence.

508

Done.

557–558

Changed to "starting from c++11".

940

Removed the second sentence altogether, it does not say anything new.

1354

I don't think this phrase is written with a dash.

[gribozavr]

Addressed review comments.

[gribozavr2]

@chandlerc has LGTM'ed this patch over chat.

llvm/docs/CodingStandards.rst

 =====================
 LLVM Coding Standards
 =====================
 
 .. contents::
    :local:
 
 Introduction
 ============
 
-This document attempts to describe a few coding standards that are being used in
-the LLVM source tree.  Although no coding standards should be regarded as
-absolute requirements to be followed in all instances, coding standards are
+This document describes coding standards that are used in the LLVM project.
+Although no coding standards should be regarded as absolute requirements to be
+followed in all instances, coding standards are
 particularly important for large-scale code bases that follow a library-based
 design (like LLVM).
 
 While this document may provide guidance for some mechanical formatting issues,
 whitespace, or other "microscopic details", these are not fixed standards.
 Always follow the golden rule:
 
 .. _Golden Rule:
 
     **If you are extending, enhancing, or bug fixing already implemented code,
     use the style that is already being used so that the source is uniform and
     easy to follow.**
 
-Note that some code bases (e.g. ``libc++``) have really good reasons to deviate
-from the coding standards.  In the case of ``libc++``, this is because the
-naming and other conventions are dictated by the C++ standard.  If you think
-there is a specific good reason to deviate from the standards here, please bring
-it up on the LLVM-dev mailing list.
+Note that some code bases (e.g. ``libc++``) have special reasons to deviate
+from the coding standards.  For example, in the case of ``libc++``, this is
+because the naming and other conventions are dictated by the C++ standard.
 
 There are some conventions that are not uniformly followed in the code base
 (e.g. the naming convention).  This is because they are relatively new, and a
 lot of code was written before they were put in place.  Our long term goal is
 for the entire codebase to follow the convention, but we explicitly *do not*
 want patches that do large-scale reformatting of existing code.  On the other
 hand, it is reasonable to rename the methods of a class if you're about to
-change it in some other way.  Just do the reformatting as a separate commit
-from the functionality change.
-  
+change it in some other way.  Please commit such changes separately to
+make code review easier.
 The ultimate goal of these guidelines is to increase the readability and
 maintainability of our common source base.
 
 Languages, Libraries, and Standards
 ===================================
 
 Most source code in LLVM and other LLVM projects using these coding standards
 is C++ code. There are some places where C code is used either due to
 environment restrictions, historical restrictions, or due to third-party source
 code imported into the tree. Generally, our preference is for standards
 conforming, modern, and portable C++ code as the implementation language of
 choice.
 
 C++ Standard Versions
 ---------------------
 
-LLVM, Clang, and LLD are currently written using C++14 conforming code,
-although we restrict ourselves to features which are available in the major
-toolchains supported as host compilers. The LLDB project is even more
-aggressive in the set of host compilers supported and thus uses still more
-features. Regardless of the supported features, code is expected to (when
-reasonable) be standard, portable, and modern C++14 code. We avoid unnecessary
-vendor-specific extensions, etc.
+Unless otherwise documented, LLVM subprojects are written using standard C++14
+code and avoid unnecessary vendor-specific extensions.
 
-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 for as much as possible. Common support libraries providing
-functionality missing from the standard library for which there are standard
-interfaces or active work on adding standard interfaces will often be
-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
-:doc:`ProgrammersManual`.
-
-Supported C++14 Language and Library Features
----------------------------------------------
-
-While LLVM, Clang, and LLD use C++14, not all features are available in all of
-the toolchains which we support. The set of features supported for use in LLVM
-is the intersection of those supported in the minimum requirements described
-in the :doc:`GettingStarted` page, section `Software`.
-The ultimate definition of this set is what build bots with those respective
-toolchains accept. Don't argue with the build bots. However, we have some
-guidance below to help you know what to expect.
+Nevertheless, we restrict ourselves to features which are available in the
+major toolchains supported as host compilers (see :doc:`GettingStarted` page,
+section `Software`).
 
 Each toolchain provides a good reference for what it accepts:
 
 * 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
 
-Other Languages
----------------
+
+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`.
+
+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.
+
+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.
 
 Go code should strive to be idiomatic. Two good sets of guidelines for what
 this means are `Effective Go`_ and `Go Code Review Comments`_.
 

 ========================
 
 Source Code Formatting
 ----------------------
 
 Commenting
 ^^^^^^^^^^
 
-Comments are one critical part of readability and maintainability.  Everyone
-knows they should comment their code, and so should you.  When writing comments,
-write them as English prose, which means they should use proper capitalization,
-punctuation, etc.  Aim to describe what the code is trying to do and why, not
-*how* it does it at a micro level. Here are a few critical things to document:
+Comments are important for readability and maintainability. When writing comments,
+write them as English prose, using proper capitalization, punctuation, etc.
+Aim to describe what the code is trying to do and why, not *how* it does it at
+a micro level. Here are a few important things to document:
 
 .. _header file comment:
 
 File Headers
 """"""""""""
 
 Every source file should have a header on it that describes the basic purpose of
-the file.  If a file does not have a header, it should not be checked into the
-tree.  The standard header looks like this:
+the file. The standard header looks like this:
 
 .. code-block:: c++
 
   //===-- llvm/Instruction.h - Instruction class definition -------*- C++ -*-===//
   //
   // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   // See https://llvm.org/LICENSE.txt for license information.
   // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception

 A few things to note about this particular format: The "``-*- C++ -*-``" string
 on the first line is there to tell Emacs that the source file is a C++ file, not
 a C file (Emacs assumes ``.h`` files are C files by default).
 
 .. note::
 
     This tag is not necessary in ``.cpp`` files.  The name of the file is also
     on the first line, along with a very short description of the purpose of the
-    file.  This is important when printing out code and flipping though lots of
-    pages.
+    file.
 
 The next section in the file is a concise note that defines the license that the
 file is released under.  This makes it perfectly clear what terms the source
 code can be distributed under and should not be modified in any way.
 
-The main body is a ``doxygen`` comment (identified by the ``///`` comment
-marker instead of the usual ``//``) describing the purpose of the file.  The
-first sentence (or a passage beginning with ``\brief``) is used as an abstract.
-Any additional information should be separated by a blank line.  If an
-algorithm is being implemented or something tricky is going on, a reference
-to the paper where it is published should be included, as well as any notes or
-*gotchas* in the code to watch out for.
+The main body is a `Doxygen <http://www.doxygen.nl/>`_ comment (identified by
+the ``///`` comment marker instead of the usual ``//``) describing the purpose
+of the file.  The first sentence (or a passage beginning with ``\brief``) is
+used as an abstract.  Any additional information should be separated by a blank
+line.  If an algorithm is based on a paper or is described in another source,
+provide a reference.
 
 Class overviews
 """""""""""""""
 
-Classes are one fundamental part of a good object oriented design.  As such, a
+Classes are a fundamental part of an object-oriented design.  As such, a
 class definition should have a comment block that explains what the class is
 used for and how it works.  Every non-trivial class is expected to have a
 ``doxygen`` comment block.
 
 Method information
 """"""""""""""""""
 
-Methods defined in a class (as well as any global functions) should also be
-documented properly.  A quick note about what it does and a description of the
-borderline behaviour is all that is necessary here (unless something
-particularly tricky or insidious is going on).  The hope is that people can
-figure out how to use your interfaces without reading the code itself.
+Methods and global functions should also be documented.  A quick note about
+what it does and a description of the edge cases is all that is necessary here.
+The reader should be able to understand how to use interfaces without reading
+the code itself.
 
 Good things to talk about here are what happens when something unexpected
-happens: does the method return null?  Abort?  Format your hard disk?
+happens, for instance, does the method return null?
 
 Comment Formatting
 ^^^^^^^^^^^^^^^^^^
 
-In general, prefer C++ style comments (``//`` for normal comments, ``///`` for
-``doxygen`` documentation comments).  They take less space, require
-less typing, don't have nesting problems, etc.  There are a few cases when it is
-useful to use C style (``/* */``) comments however:
+In general, prefer C++-style comments (``//`` for normal comments, ``///`` for
+``doxygen`` documentation comments).  There are a few cases when it is
+useful to use C-style (``/* */``) comments however:
 
-#. When writing C code: Obviously if you are writing C code, use C style
-   comments.
+#. When writing C code to be compatible with C89.
 
 #. When writing a header file that may be ``#include``\d by a C source file.
 
-#. When writing a source file that is used by a tool that only accepts C style
+#. When writing a source file that is used by a tool that only accepts C-style
    comments.
 
 #. When documenting the significance of constants used as actual parameters in
    a call. This is most helpful for ``bool`` parameters, or passing ``0`` or
-   ``nullptr``. Typically you add the formal parameter name, which ought to be
+   ``nullptr``. The comment should contain the parameter name, which ought to be
    meaningful. For example, it's not clear what the parameter means in this call:
 
    .. code-block:: c++
 
      Object.emitName(nullptr);
 
    An in-line C-style comment makes the intent obvious:
 
    .. code-block:: c++
 
      Object.emitName(/*Prefix=*/nullptr);
 
 Commenting out large blocks of code is discouraged, but if you really have to do
 this (for documentation purposes or as a suggestion for debug printing), use
 ``#if 0`` and ``#endif``. These nest properly and are better behaved in general
 than C style comments.
 
 Doxygen Use in Documentation Comments
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Use the ``\file`` command to turn the standard file header into a file-level
 comment.
 
 Include descriptive paragraphs for all public interfaces (public classes,
-member and non-member functions).  Don't just restate the information that can
+member and non-member functions).  Avoid restating the information that can
 be inferred from the API name.  The first sentence (or a paragraph beginning
 with ``\brief``) is used as an abstract. Try to use a single sentence as the
 ``\brief`` adds visual clutter.  Put detailed discussion into separate
 paragraphs.
 
 To refer to parameter names inside a paragraph, use the ``\p name`` command.
 Don't use the ``\arg name`` command since it starts a new paragraph that
 contains documentation for the parameter.

 comments (not necessarily in Doxygen markup) to explain implementation details
 as needed.
 
 Don't duplicate function or class name at the beginning of the comment.
 For humans it is obvious which function or class is being documented;
 automatic documentation processing tools are smart enough to bind the comment
 to the correct declaration.
 
-Wrong:
+Avoid:
 
 .. code-block:: c++
 
-  // In Something.h:
+  // Example.h:
 
-  /// Something - An abstraction for some complicated thing.
-  class Something {
-  public:
-    /// fooBar - Does foo and bar.
-    void fooBar();
-  };
+  // example - Does something important.
+  void example();
 
-  // In Something.cpp:
+  // Example.cpp:
 
-  /// fooBar - Does foo and bar.
-  void Something::fooBar() { ... }
+  // example - Does something important.
+  void example() { ... }
 
-Correct:
+Preferred:
 
 .. code-block:: c++
 
-  // In Something.h:
+  // Example.h:
 
-  /// An abstraction for some complicated thing.
-  class Something {
-  public:
-    /// Does foo and bar.
-    void fooBar();
-  };
-
-  // In Something.cpp:
-
-  // Builds a B-tree in order to do foo.  See paper by...
-  void Something::fooBar() { ... }
-
-It is not required to use additional Doxygen features, but sometimes it might
-be a good idea to do so.
-
-Consider:
-
-* adding comments to any narrow namespace containing a collection of
-  related functions or types;
+  /// Does something important.
+  void example();
 
-* using top-level groups to organize a collection of related functions at
-  namespace scope where the grouping is smaller than the namespace;
+  // Example.cpp:
 
-* using member groups and additional comments attached to member
-  groups to organize within a class.
-
-For example:
-
-.. code-block:: c++
-
-  class Something {
-    /// \name Functions that do Foo.
-    /// @{
-    void fooBar();
-    void fooBaz();
-    /// @}
-    ...
-  };
+  /// Builds a B-tree in order to do foo.  See paper by...
+  void example() { ... }
 
 ``#include`` Style
 ^^^^^^^^^^^^^^^^^^
 
 Immediately after the `header file comment`_ (and include guards if working on a
 header file), the `minimal list of #includes`_ required by the file should be
 listed.  We prefer these ``#include``\s to be listed in this order:
 

 similarly include its own headers before including llvm headers.  This rule
 applies to all LLVM subprojects.
 
 .. _fit into 80 columns:
 
 Source Code Width
 ^^^^^^^^^^^^^^^^^
 
-Write your code to fit within 80 columns of text.  This helps those of us who
-like to print out code and look at your code in an ``xterm`` without resizing
-it.
+Write your code to fit within 80 columns.
 
-The longer answer is that there must be some limit to the width of the code in
-order to reasonably allow developers to have multiple files side-by-side in
+There must be some limit to the width of the code in
+order to allow developers to have multiple files side-by-side in
 windows on a modest display.  If you are going to pick a width limit, it is
 somewhat arbitrary but you might as well pick something standard.  Going with 90
 columns (for example) instead of 80 columns wouldn't add any significant value
 and would be detrimental to printing out code.  Also many other projects have
 standardized on 80 columns, so some people have already configured their editors
 for it (vs something else, like 90 columns).
 
-This is one of many contentious issues in coding standards, but it is not up for
-debate.
-
 Whitespace
 ^^^^^^^^^^
 
 In all cases, prefer spaces to tabs in source files.  People have different
 preferred indentation levels, and different styles of indentation that they
 like; this is fine.  What isn't fine is that different editors/viewers expand
 tabs out to different tab stops.  This can cause your code to look completely
 unreadable, and it is not worth dealing with.
 
-As always, follow the `Golden Rule`_ above: follow the style of
-existing code if you are modifying and extending it.  If you like four spaces of
-indentation, **DO NOT** do that in the middle of a chunk of code with two spaces
-of indentation.  Also, do not reindent a whole source file: it makes for
-incredible diffs that are absolutely worthless.
-
-Do not commit changes that include trailing whitespace. If you find trailing
-whitespace in a file, do not remove it unless you're otherwise changing that
-line of code. Some common editors will automatically remove trailing whitespace
-when saving a file which causes unrelated changes to appear in diffs and
-commits.
-
-Indent Code Consistently
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-Okay, in your first year of programming you were told that indentation is
-important. If you didn't believe and internalize this then, now is the time.
-Just do it. With the introduction of C++11, there are some new formatting
-challenges that merit some suggestions to help have consistent, maintainable,
-and tool-friendly formatting and indentation.
+As always, follow the `Golden Rule`_ above: follow the style of existing code
+if you are modifying and extending it.
+
+Do not add trailing whitespace.  Some common editors will automatically remove
+trailing whitespace when saving a file which causes unrelated changes to appear
+in diffs and commits.
 
 Format Lambdas Like Blocks Of Code
 """"""""""""""""""""""""""""""""""
 
-When formatting a multi-line lambda, format it like a block of code, that's
-what it is. If there is only one multi-line lambda in a statement, and there
-are no expressions lexically after it in the statement, drop the indent to the
-standard two space indent for a block of code, as if it were an if-block opened
-by the preceding part of the statement:
+When formatting a multi-line lambda, format it like a block of code. If there
+is only one multi-line lambda in a statement, and there are no expressions
+lexically after it in the statement, drop the indent to the standard two space
+indent for a block of code, as if it were an if-block opened by the preceding
+part of the statement:
 
 .. code-block:: c++
 
   std::sort(foo.begin(), foo.end(), [&](Foo a, Foo b) -> bool {
     if (a.blah < b.blah)
       return true;
     if (a.baz < b.baz)
       return true;
     return a.bam < b.bam;
   });
 
 To take best advantage of this formatting, if you are designing an API which
-accepts a continuation or single callable argument (be it a functor, or
+accepts a continuation or single callable argument (be it a function object, or
 a ``std::function``), it should be the last argument if at all possible.
 
-If there are multiple multi-line lambdas in a statement, or there is anything
-interesting after the lambda in the statement, indent the block two spaces from
-the indent of the ``[]``:
+If there are multiple multi-line lambdas in a statement, or additional
+parameters after the lambda, indent the block two spaces from the indent of the
+``[]``:
 
 .. code-block:: c++
 
   dyn_switch(V->stripPointerCasts(),
              [] (PHINode *PN) {
                // process phis...
              },
              [] (SelectInst *SI) {
                // process selects...
              },
              [] (LoadInst *LI) {
                // process loads...
              },
              [] (AllocaInst *AI) {
                // process allocas...
              });
 
 Braced Initializer Lists
 """"""""""""""""""""""""
 
-With C++11, there are significantly more uses of braced lists to perform
-initialization. These allow you to easily construct aggregate temporaries in
-expressions among other niceness. They now have a natural way of ending up
-nested within each other and within function calls in order to build up
-aggregates (such as option structs) from local variables. To make matters
-worse, we also have many more uses of braces in an expression context that are
-*not* performing initialization.
+Starting from C++11, there are significantly more uses of braced lists to
+perform initialization. For example, they can be used to construct aggregate
+temporaries in expressions. They now have a natural way of ending up nested
+within each other and within function calls in order to build up aggregates
+(such as option structs) from local variables.
 
 The historically common formatting of braced initialization of aggregate
 variables does not mix cleanly with deep nesting, general expression contexts,
 function arguments, and lambdas. We suggest new code use a simple rule for
 formatting braced initialization lists: act as-if the braces were parentheses
 in a function call. The formatting rules exactly match those already well
 understood for formatting nested function calls. Examples:
 

 .. _Clang Format: https://clang.llvm.org/docs/ClangFormat.html
 
 Language and Compiler Issues
 ----------------------------
 
 Treat Compiler Warnings Like Errors
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-If your code has compiler warnings in it, something is wrong --- you aren't
-casting values correctly, you have "questionable" constructs in your code, or
-you are doing something legitimately wrong.  Compiler warnings can cover up
-legitimate errors in output and make dealing with a translation unit difficult.
-
-It is not possible to prevent all warnings from all compilers, nor is it
-desirable.  Instead, pick a standard compiler (like ``gcc``) that provides a
-good thorough set of warnings, and stick to it.  At least in the case of
-``gcc``, it is possible to work around any spurious errors by changing the
-syntax of the code slightly.  For example, a warning that annoys me occurs when
-I write code like this:
+Compiler warnings are often useful and help improve the code.  Those that are
+not useful, can be often suppressed with a small code change. For example, an
+assignment in the ``if`` condition is often a typo:
 
 .. code-block:: c++
 
   if (V = getValue()) {
     ...
   }
 
-``gcc`` will warn me that I probably want to use the ``==`` operator, and that I
-probably mistyped it.  In most cases, I haven't, and I really don't want the
-spurious errors.  To fix this particular problem, I rewrite the code like
-this:
+Several compilers will print a warning for the code above. It can be suppressed
+by adding parentheses:
 
 .. code-block:: c++
 
   if ((V = getValue())) {
     ...
   }
 
-which shuts ``gcc`` up.  Any ``gcc`` warning that annoys you can be fixed by
-massaging the code appropriately.
-
 Write Portable Code
 ^^^^^^^^^^^^^^^^^^^
 
-In almost all cases, it is possible and within reason to write completely
-portable code.  If there are cases where it isn't possible to write portable
-code, isolate it behind a well defined (and well documented) interface.
-
-In practice, this means that you shouldn't assume much about the host compiler
-(and Visual Studio tends to be the lowest common denominator).  If advanced
-features are used, they should only be an implementation detail of a library
-which has a simple exposed API, and preferably be buried in ``libSystem``.
+In almost all cases, it is possible to write completely portable code.  When
+you need to rely on non-portable code, put it behind a well-defined and
+well-documented interface.
 
 Do not use RTTI or Exceptions
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-In an effort to reduce code and executable size, LLVM does not use RTTI
-(e.g. ``dynamic_cast<>;``) or exceptions.  These two language features violate
-the general C++ principle of *"you only pay for what you use"*, causing
-executable bloat even if exceptions are never used in the code base, or if RTTI
-is never used for a class.  Because of this, we turn them off globally in the
-code.
+In an effort to reduce code and executable size, LLVM does not use exceptions
+or RTTI (`runtime type information
+<https://en.wikipedia.org/wiki/Run-time_type_information>`_, for example,
+``dynamic_cast<>``).
 
 That said, LLVM does make extensive use of a hand-rolled form of RTTI that use
 templates like :ref:`isa\<>, cast\<>, and dyn_cast\<> <isa>`.
 This form of RTTI is opt-in and can be
-:doc:`added to any class <HowToSetUpLLVMStyleRTTI>`. It is also
-substantially more efficient than ``dynamic_cast<>``.
+:doc:`added to any class <HowToSetUpLLVMStyleRTTI>`.
 
 .. _static constructor:
 
 Do not use Static Constructors
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Static constructors and destructors (e.g. global variables whose types have a
+Static constructors and destructors (e.g., global variables whose types have a
 constructor or destructor) should not be added to the code base, and should be
-removed wherever possible.  Besides `well known problems
-<https://yosefk.com/c++fqa/ctors.html#fqa-10.12>`_ where the order of
-initialization is undefined between globals in different source files, the
-entire concept of static constructors is at odds with the common use case of
-LLVM as a library linked into a larger application.
-  
-Consider the use of LLVM as a JIT linked into another application (perhaps for
-`OpenGL, custom languages <https://llvm.org/Users.html>`_, `shaders in movies
-<https://llvm.org/devmtg/2010-11/Gritz-OpenShadingLang.pdf>`_, etc). Due to the
-design of static constructors, they must be executed at startup time of the
-entire application, regardless of whether or how LLVM is used in that larger
-application.  There are two problems with this:
-
-* The time to run the static constructors impacts startup time of applications
-  --- a critical time for GUI apps, among others.
-  
-* The static constructors cause the app to pull many extra pages of memory off
-  the disk: both the code for the constructor in each ``.o`` file and the small
-  amount of data that gets touched. In addition, touched/dirty pages put more
-  pressure on the VM system on low-memory machines.
-
-We would really like for there to be zero cost for linking in an additional LLVM
-target or other library into an application, but static constructors violate
-this goal.
-  
-That said, LLVM unfortunately does contain static constructors.  It would be a
-`great project <https://llvm.org/PR11944>`_ for someone to purge all static
-constructors from LLVM, and then enable the ``-Wglobal-constructors`` warning
-flag (when building with Clang) to ensure we do not regress in the future.
+removed wherever possible.
+
+Globals in different source files are initialized in `arbitrary order
+<https://yosefk.com/c++fqa/ctors.html#fqa-10.12>`, making the code more
+difficult to reason about.
+Static constructors have negative impact on launch time of programs that use
+LLVM as a library. We would really like for there to be zero cost for linking
+in an additional LLVM target or other library into an application, but static
+constructors undermine this goal.
 
 Use of ``class`` and ``struct`` Keywords
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 In C++, the ``class`` and ``struct`` keywords can be used almost
 interchangeably. The only difference is when they are used to declare a class:
 ``class`` makes all members private by default while ``struct`` makes all
 members public by default.
 
-Unfortunately, not all compilers follow the rules and some will generate
-different symbols based on whether ``class`` or ``struct`` was used to declare
-the symbol (e.g., MSVC).  This can lead to problems at link time.
-
 * All declarations and definitions of a given ``class`` or ``struct`` must use
   the same keyword.  For example:
 
 .. code-block:: c++
 
-  class Foo;
+  // Avoid if `Example` is defined as a struct.
+  class Example;
 
-  // Breaks mangling in MSVC.
-  struct Foo { int Data; };
+  // OK.
+  struct Example;
 
-* As a rule of thumb, ``struct`` should be kept to structures where *all*
-  members are declared public.
+  struct Example { ... };
+
+* ``struct`` should be used when *all* members are declared public.
 
 .. code-block:: c++
 
-  // Foo feels like a class... this is strange.
+  // Avoid using `struct` here, use `class` instead.
   struct Foo {
   private:
     int Data;
   public:
     Foo() : Data(0) { }
     int getData() const { return Data; }
     void setData(int D) { Data = D; }
   };
 
-  // Bar isn't POD, but it does look like a struct.
+  // OK to use `struct`: all members are public.
   struct Bar {
     int Data;
     Bar() : Data(0) { }
   };
 
 Do not use Braced Initializer Lists to Call a Constructor
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-In C++11 there is a "generalized initialization syntax" which allows calling
-constructors using braced initializer lists. Do not use these to call
-constructors with any interesting logic or if you care that you're calling some
+Starting from C++11 there is a "generalized initialization syntax" which allows
+calling constructors using braced initializer lists. Do not use these to call
+constructors with non-trivial logic or if you care that you're calling some
 *particular* constructor. Those should look like function calls using
 parentheses rather than like aggregate initialization. Similarly, if you need
 to explicitly name the type and call its constructor to create a temporary,
 don't use a braced initializer list. Instead, use a braced initializer list
 (without any type for temporaries) when doing aggregate initialization or
 something notionally equivalent. Examples:
 
 .. code-block:: c++
 
   class Foo {
   public:
     // Construct a Foo by reading data from the disk in the whizbang format, ...
     Foo(std::string filename);
 
     // Construct a Foo by looking up the Nth element of some global data ...
     Foo(int N);
 
     // ...
   };
 
-  // The Foo constructor call is very deliberate, no braces.
+  // The Foo constructor call is reading a file, don't use braces to call it.
   std::fill(foo.begin(), foo.end(), Foo("name"));
 
-  // The pair is just being constructed like an aggregate, use braces.
+  // The pair is being constructed like an aggregate, use braces.
   bar_map.insert({my_key, my_value});
 
 If you use a braced initializer list when initializing a variable, use an equals before the open curly brace:
 
 .. code-block:: c++
 
   int data[] = {0, 1, 2, 3};
 

 
 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.
+Use ``auto &`` for values and ``auto *`` for pointers unless you need to make a
+copy.
 
 .. 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(); }
 
 Beware of non-determinism due to ordering of pointers
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 In general, there is no relative ordering among pointers. As a result,
 when unordered containers like sets and maps are used with pointer keys
 the iteration order is undefined. Hence, iterating such containers may
 result in non-deterministic code generation. While the generated code
-might not necessarily be "wrong code", this non-determinism might result
-in unexpected runtime crashes or simply hard to reproduce bugs on the
-customer side making it harder to debug and fix.
+might work correctly, non-determinism can make it harder to reproduce bugs and
+debug the compiler.
 
-As a rule of thumb, in case an ordered result is expected, remember to
+In case an ordered result is expected, remember to
 sort an unordered container before iteration. Or use ordered containers
-like vector/MapVector/SetVector if you want to iterate pointer keys.
+like ``vector``/``MapVector``/``SetVector`` if you want to iterate pointer
+keys.
 
 Beware of non-deterministic sorting order of equal elements
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-std::sort uses a non-stable sorting algorithm in which the order of equal
-elements is not guaranteed to be preserved. Thus using std::sort for a
+``std::sort`` uses a non-stable sorting algorithm in which the order of equal
+elements is not guaranteed to be preserved. Thus using ``std::sort`` for a
 container having equal elements may result in non-determinstic behavior.
 To uncover such instances of non-determinism, LLVM has introduced a new
 llvm::sort wrapper function. For an EXPENSIVE_CHECKS build this will randomly
-shuffle the container before sorting. As a rule of thumb, always make sure to
-use llvm::sort instead of std::sort.
+shuffle the container before sorting. Default to using ``llvm::sort`` instead
+of ``std::sort``.
 
 Style Issues
 ============
 
 The High-Level Issues
 ---------------------
 
 Self-contained Headers
 ^^^^^^^^^^^^^^^^^^^^^^
 
-Header files should be self-contained (compile on their own) and end in .h.
-Non-header files that are meant for inclusion should end in .inc and be used
-sparingly.
+Header files should be self-contained (compile on their own) and end in ``.h``.
+Non-header files that are meant for inclusion should end in ``.inc`` and be
+used sparingly.
 
 All header files should be self-contained. Users and refactoring tools should
 not have to adhere to special conditions to include the header. Specifically, a
 header should have header guards and include all other headers it needs.
 
 There are rare cases where a file designed to be included is not
 self-contained. These are typically intended to be included at unusual
 locations, such as the middle of another file. They might not use header

 
 Use Early Exits and ``continue`` to Simplify Code
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 When reading code, keep in mind how much state and how many previous decisions
 have to be remembered by the reader to understand a block of code.  Aim to
 reduce indentation where possible when it doesn't make it more difficult to
 understand the code.  One great way to do this is by making use of early exits
-and the ``continue`` keyword in long loops.  As an example of using an early
-exit from a function, consider this "bad" code:
+and the ``continue`` keyword in long loops. Consider this code that does not
+use an early exit:
 
 .. code-block:: c++
 
   Value *doSomething(Instruction *I) {
     if (!I->isTerminator() &&
         I->hasOneUse() && doOtherThing(I)) {
       ... some long code ....
     }

 of the loop, it makes it easier to describe why the conditions are true, and it
 makes it obvious to the reader that there is no ``else`` coming up that they
 have to push context into their brain for.  If a loop is large, this can be a
 big understandability win.
 
 Don't use ``else`` after a ``return``
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-For similar reasons above (reduction of indentation and easier reading), please
+For similar reasons as above (reduction of indentation and easier reading), please
 do not use ``'else'`` or ``'else if'`` after something that interrupts control
-flow --- like ``return``, ``break``, ``continue``, ``goto``, etc. For
-example, this is *bad*:
+flow --- like ``return``, ``break``, ``continue``, ``goto``, etc. For example:
 
 .. code-block:: c++
 
   case 'J': {
     if (Signed) {
       Type = Context.getsigjmp_bufType();
       if (Type.isNull()) {
         Error = ASTContext::GE_Missing_sigjmp_buf;
         return QualType();
       } else {
-        break;
+        break; // Unnecessary.
       }
     } else {
       Type = Context.getjmp_bufType();
       if (Type.isNull()) {
         Error = ASTContext::GE_Missing_jmp_buf;
         return QualType();
       } else {
-        break;
+        break; // Unnecessary.
       }
     }
   }
 
 It is better to write it like this:
 
 .. code-block:: c++
 
if (BarList[I]->isFoo()) {
       FoundFoo = true;
       break;
     }
 
   if (FoundFoo) {
     ...
   }
 
-This sort of code is awkward to write, and is almost always a bad sign.  Instead
-of this sort of loop, we strongly prefer to use a predicate function (which may
-be `static`_) that uses `early exits`_ to compute the predicate.  We prefer the
-code to be structured like this:
+Instead of this sort of loop, we prefer to use a predicate function (which may
+be `static`_) that uses `early exits`_:
 
 .. code-block:: c++
 
   /// \returns true if the specified list has an element that is a foo.
   static bool containsFoo(const std::vector<Bar*> &List) {
     for (unsigned I = 0, E = List.size(); I != E; ++I)
       if (List[I]->isFoo())
         return true;
.. code-block:: c++
       };
   
 As an exception, classes that mimic STL classes can have member names in STL's
 style of lower-case words separated by underscores (e.g. ``begin()``,
 ``push_back()``, and ``empty()``). Classes that provide multiple
 iterators should add a singular prefix to ``begin()`` and ``end()``
 (e.g. ``global_begin()`` and ``use_begin()``).
 
-Here are some examples of good and bad names:
+Here are some examples:
 
 .. code-block:: c++
 
   class VehicleMaker {
     ...
-    Factory<Tire> F;            // Bad -- abbreviation and non-descriptive.
-    Factory<Tire> Factory;      // Better.
-    Factory<Tire> TireFactory;  // Even better -- if VehicleMaker has more than one
+    Factory<Tire> F;            // Avoid: a non-descriptive abbreviation.
+    Factory<Tire> Factory;      // Better: more descriptive.
+    Factory<Tire> TireFactory;  // Even better: if VehicleMaker has more than one
                                 // kind of factories.
   };
 
   Vehicle makeVehicle(VehicleType Type) {
-    VehicleMaker M;                         // Might be OK if having a short life-span.
-    Tire Tmp1 = M.makeTire();               // Bad -- 'Tmp1' provides no information.
-    Light Headlight = M.makeLight("head");  // Good -- descriptive.
+    VehicleMaker M;                         // Might be OK if scope is small.
+    Tire Tmp1 = M.makeTire();               // Avoid: 'Tmp1' provides no information.
+    Light Headlight = M.makeLight("head");  // Good: descriptive.
     ...
   }
 
 Assert Liberally
 ^^^^^^^^^^^^^^^^
 
 Use the "``assert``" macro to its fullest.  Check all of your preconditions and
 assumptions, you never know when a bug (not necessarily even yours) might be

 Do Not Use ``using namespace std``
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 In LLVM, we prefer to explicitly prefix all identifiers from the standard
 namespace with an "``std::``" prefix, rather than rely on "``using namespace
 std;``".
 
 In header files, adding a ``'using namespace XXX'`` directive pollutes the
-namespace of any source file that ``#include``\s the header.  This is clearly a
-bad thing.
+namespace of any source file that ``#include``\s the header, creating
+maintenance issues.
 
 In implementation files (e.g. ``.cpp`` files), the rule is more of a stylistic
 rule, but is still important.  Basically, using explicit namespace prefixes
 makes the code **clearer**, because it is immediately obvious what facilities
 are being used and where they are coming from. And **more portable**, because
 namespace clashes cannot occur between LLVM code and other namespaces.  The
 portability rule is important because different standard library implementations
 expose different symbols (potentially ones they shouldn't), and future revisions

 -------------------
 
 This section describes preferred low-level formatting guidelines along with
 reasoning on why we prefer them.
 
 Spaces Before Parentheses
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-We prefer to put a space before an open parenthesis only in control flow
-statements, but not in normal function call expressions and function-like
-macros.  For example, this is good:
-
-.. code-block:: c++
-
-  if (X) ...
-  for (I = 0; I != 100; ++I) ...
-  while (LLVMRocks) ...
-
-  somefunc(42);
-  assert(3 != 4 && "laws of math are failing me");
-  
-  A = foo(42, 92) + bar(X);
-
-and this is bad:
+Put a space before an open parenthesis only in control flow statements, but not
+in normal function call expressions and function-like macros.  For example:
 
 .. code-block:: c++
 
-  if(X) ...
-  for(I = 0; I != 100; ++I) ...
-  while(LLVMRocks) ...
+  if (X) ...
+  for (I = 0; I != 100; ++I) ...
+  while (LLVMRocks) ...
 
-  somefunc (42);
-  assert (3 != 4 && "laws of math are failing me");
-  
-  A = foo (42, 92) + bar (X);
+  somefunc(42);
+  assert(3 != 4 && "laws of math are failing me");
+  A = foo(42, 92) + bar(X);
 
 The reason for doing this is not completely arbitrary.  This style makes control
-flow operators stand out more, and makes expressions flow better. The function
-call operator binds very tightly as a postfix operator.  Putting a space after a
-function name (as in the last example) makes it appear that the code might bind
-the arguments of the left-hand-side of a binary operator with the argument list
-of a function and the name of the right side.  More specifically, it is easy to
-misread the "``A``" example as:
-
-.. code-block:: c++
-
-  A = foo ((42, 92) + bar) (X);
-
-when skimming through the code.  By avoiding a space in a function, we avoid
-this misinterpretation.
+flow operators stand out more, and makes expressions flow better.
 
 Prefer Preincrement
 ^^^^^^^^^^^^^^^^^^^
 
 Hard fast rule: Preincrement (``++X``) may be no slower than postincrement
 (``X++``) and could very well be a lot faster than it.  Use preincrementation
 whenever possible.
 
 The semantics of postincrement include making a copy of the value being
 incremented, returning it, and then preincrementing the "work value".  For
 primitive types, this isn't a big deal. But for iterators, it can be a huge
 issue (for example, some iterators contains stack and set objects in them...
 copying an iterator could invoke the copy ctor's of these as well).  In general,
 get in the habit of always using preincrement, and you won't have a problem.
 
 
 Namespace Indentation
 ^^^^^^^^^^^^^^^^^^^^^
 
 In general, we strive to reduce indentation wherever possible.  This is useful
-because we want code to `fit into 80 columns`_ without wrapping horribly, but
+because we want code to `fit into 80 columns`_ without excessive wrapping, but
 also because it makes it easier to understand the code. To facilitate this and
 avoid some insanely deep nesting on occasion, don't indent namespaces. If it
 helps readability, feel free to add a comment indicating what namespace is
 being closed by a ``}``.  For example:
 
 .. code-block:: c++
 
   namespace llvm {

 
 The problem with anonymous namespaces is that they naturally want to encourage
 indentation of their body, and they reduce locality of reference: if you see a
 random function definition in a C++ file, it is easy to see if it is marked
 static, but seeing if it is in an anonymous namespace requires scanning a big
 chunk of the file.
 
 Because of this, we have a simple guideline: make anonymous namespaces as small
-as possible, and only use them for class declarations.  For example, this is
-good:
+as possible, and only use them for class declarations.  For example:
 
 .. code-block:: c++
 
   namespace {
   class StringSort {
   ...
   public:
     StringSort(...)
     bool operator<(const char *RHS) const;
   };
   } // end anonymous namespace
 
   static void runHelper() { 
     ... 
   }
 
   bool StringSort::operator<(const char *RHS) const {
     ...
   }
 
-This is bad:
+Avoid putting declarations other than classes into anonymous namespaces:
 
 .. code-block:: c++
 
   namespace {
 
-  class StringSort {
-  ...
-  public:
-    StringSort(...)
-    bool operator<(const char *RHS) const;
-  };
+  // ... many declarations ...
 
-  void runHelper() { 
-    ... 
+  void runHelper() {
+    ...
   }
 
-  bool StringSort::operator<(const char *RHS) const {
-    ...
-  }
+  // ... many declarations ...
 
   } // end anonymous namespace
 
-This is bad specifically because if you're looking at "``runHelper``" in the middle
-of a large C++ file, that you have no immediate way to tell if it is local to
-the file.  When it is marked static explicitly, this is immediately obvious.
-Also, there is no reason to enclose the definition of "``operator<``" in the
-namespace just because it was declared there.
+When you are looking at "``runHelper``" in the middle of a large C++ file,
+you have no immediate way to tell if this function is local to the file.  In
+contrast, when the function is marked static, you don't need to cross-reference
+faraway places in the file to tell that the function is local.
 
 See Also
 ========
 
 A lot of these comments and recommendations have been culled from other sources.
 Two particularly important books for our work are:
 
 #. `Effective C++

llvm/docs/index.rst

.. toctree::
    Lexicon
 
 `Introduction to the LLVM Compiler`__
   Presentation providing a users introduction to LLVM.
 
   .. __: http://llvm.org/pubs/2008-10-04-ACAT-LLVM-Intro.html
 
 `Intro to LLVM`__
-  Book chapter providing a compiler hacker's introduction to LLVM.
+  A chapter from the book "The Architecture of Open Source Applications" that
+  describes high-level design decisions that shaped LLVM.
 
   .. __: http://www.aosabook.org/en/llvm.html
 
 
 `LLVM: A Compilation Framework for Lifelong Program Analysis & Transformation`__
   Design overview.
 
   .. __: http://llvm.org/pubs/2004-01-30-CGO-LLVM.html