[Documentation] Proposal for plan to change variable names

[michaelplatings]

Summary

This proposal summarizes feedback gathered in this thread: http://lists.llvm.org/pipermail/llvm-dev/2019-February/130083.html and aims to ultimately form it into a plan that can be agreed upon.

It is not expected that reviewers agree with the plan, especially its later stages, but it shouldn't misrepresent any views previously expressed, contain obvious errors or leave major gaps.

[jhenderson]

llvm/docs/Proposals/VariableNames.rst

77 ↗

(On Diff #190241)

Probably also worth noting that lower_case is consistent with the C++ standard, and maybe other projects like Boost?

[t.p.northover]

llvm/docs/Proposals/VariableNames.rst

46–47 ↗

(On Diff #190241)

WTF!

133 ↗

(On Diff #190241)

How was this list derived? It seems a bit skewed towards mid-end development over back-end.

MRI is MachineRegisterInfo to me (and about 70% of LLVM code by a quick grep); and TLI is TargetLoweringInfo (rarer than TargetLibraryInfo this time, but still about 30% of uses).

I know someone specifically mentioned being surprised by conflicting acronyms when moving to different parts of LLVM, but I think it's rare enough that we should still allow them.

[michaelplatings]

llvm/docs/Proposals/VariableNames.rst

77 ↗

(On Diff #190241)

I've avoided referencing projects that don't also capitalise class names, as they need to balance different concerns to those we're considering.

133 ↗

(On Diff #190241)

The list was largely compiled from those mentioned in the RFC thread - more can be added in future. I made a mistake with MRI, I've changed it to MachineRegisterInfo.
Was TargetLoweringInfo renamed to TargetLowering? In that case TLI seems less appropriate. If this is controversial then I'll remove it from the proposal for now.

[MyDeveloperDay]

llvm/docs/Proposals/VariableNames.rst

297 ↗

(On Diff #190253)

clang-tidy can autoformat any modification with -format-style=file and it will use a projects .clang-format file to clang-format just the lines that were changed by clang-tidy.

That removes the need for a separate clang-format run, this should at least help minimize the other changes caused by formatting code outside of the rename, or the need to run git clang-format.

Potentially you might want to run clang-tidy with JUST the readability-identifier-naming rules turned on so it only fixes those issues and not anything else... (otherwise clang-tidy is going to have a field day!)

[t.p.northover]

llvm/docs/Proposals/VariableNames.rst

133 ↗

(On Diff #190241)

Wow, I never noticed the acronym didn't really match up for TLI! Yep, lowering seems reasonable under that.

[michaelplatings]

llvm/docs/Proposals/VariableNames.rst

297 ↗

(On Diff #190253)

Thanks, I've updated the plan accordingly.

[ruiu]

llvm/docs/Proposals/VariableNames.rst

220 ↗

(On Diff #190258)

By the way, do you have anything in mind about what tool can be used for batch renaming? Do we have to hack it up based on clang-format or something?

[mehdi_amini]

llvm/docs/Proposals/VariableNames.rst

144 ↗

(On Diff #190258)

side note: I feel that single letter variable name are annoying (can't easily search in a text editor for example), I would rather use a short name like func.

264 ↗

(On Diff #190258)

This can be seen as an advantage for a mass rename: it is a "one-time cost" (that can be helped by clang-tidy), while a progressive renaming will lead to many spurious merge conflicts (and successful merge breaking the builds, or worse changing the runtime behavior!!) for downstream users for multiple years.
It seems be easier to deal with a one time merge that is NFC rather than having many semantic change patches along the years that create conflict on variable naming.

[lattner]

this is a really great summary of the situation, thank you for collecting this in such a methodical way!

llvm/docs/Proposals/VariableNames.rst

90 ↗

(On Diff #190258)

FWIW, I personally consider this to be a totally orthogonal discussion to the other issues, I think it would be nice to separate it out just so we have some hope of converging an already contentious topic. Ratcheting forward one decision at a time seems like better way to make progress.

141 ↗

(On Diff #190258)

Small point, but I think that "block" is a much better name than bb in practice.

144 ↗

(On Diff #190258)

Yeah, maybe this could include a list, like f, fn, func, etc. There is a diversity of contractions used here. Standardizing this is a theoretically nice thing, but a distraction from the core issue in this discussion and not particularly important in the big scheme of things (unlikely to cause confusion).

254 ↗

(On Diff #190258)

FWIW, It has never been a goal for LLVM To prevent downstream merge conflicts. The "party line" (painful as it may be in practice) is that mainline moves ahead full speed without worrying about this, and anyone adversely affected should work to get their changes merged to mainline.

This isn't likely to affect the public APIs in llvm/include in a significant way, so it really only affects people with diffs against core code.

46–47 ↗

(On Diff #190241)

seriously :-)

[michaelplatings]

llvm/docs/Proposals/VariableNames.rst

90 ↗

(On Diff #190258)

I agree that it's orthogonal to reducing the number of acronyms (my personal intention with all this) but there seems to be a strong sentiment which we can't ignore that differentiating member variables should be considered as part of changing naming policy. For that reason I'm including it at this stage. I hope that results gathered from the experimentation phase will inform the discussion and we can agree at that point on a suitable way forward, which may be to defer this particular change as you suggest.

144 ↗

(On Diff #190258)

I was under the misconception that F was one of the acronyms that people were fond of. I've removed it for now.

220 ↗

(On Diff #190258)

Primarily clang-tidy. There will be some extra work to resolve name conflicts (there are some variables named Int for example) but we'll flush out such issues during the experimentation phase (currently step 3 in the provisional plan).

254 ↗

(On Diff #190258)

Yes, and I'm fully supportive of that policy. But if we can make downstream folks' lives easier without compromising our choices upstream then I'm happy to put in the effort to do that.

264 ↗

(On Diff #190258)

True, although see Chris Lattner's comment about the "party line" above - on that basis it's not something that should sway our decision.

[rupprecht]

Thanks for going through all this effort. I think this captures the discussion pretty well. Thanks for including all the citations. If anyone wants to continue on some more points, should we reply here, or reply on the RFC thread?

llvm/docs/Proposals/VariableNames.rst

86 ↗

(On Diff #190413)

I also prefer this type... you could add my name here, but maybe I should ask more generally: it's good that the discussion points in favor/against each style are listed, but as far as individuals that approve/oppose a style, do we plan to run some kind of poll and go with whichever has a majority vote? (Should Chandler/Chris get more votes than me? :) )

97 ↗

(On Diff #190413)

Similarly, I also (slightly) oppose this style, but I'm not sure if you need to add my name to the list, or if we're just going to tally votes at some point

141 ↗

(On Diff #190413)

An important detail that seems to be left out -- not just here, but also the main llvm style guide -- is scoping of these variables.

For example:

for (DeterministicFiniteAutomaton* dfa : allTheDfas) // or all_the_dfas
  dfa->DoSomething();

dfa is great here, and in fact, a long name might just be distracting.

But, for something like:

DeterministicFiniteAutomaton* dfa = GetSomeSpecificDfa();
// ... 200 lines of other stuff ...
dfa->DoSomething(); // I forget, which dfa is this?

dfa is not a good name -- something that has such a long scope needs a more descriptive name, e.g. which dfa we're manipulating.

Which is a long way of saying: I don't think that having a blessed list of acronyms is a good idea. It's going to be entirely dependent on the context. We should just say that acronyms can be considered one word, and is a fine way of using short variable names. (Listing a couple of these as common examples is fine, though).

297 ↗

(On Diff #190413)

Can we take a stab at defining "suitable delay" here? Would something like 2 weeks be enough? Or maybe a longer time (e.g. 1 month) for the first experiment, shorter times (e.g. 2 weeks) for the next few, and no delay for the remaining ones?

[rupprecht]

Since this isn't the actual policy change, just a snapshot of an ongoing discussion, I think this fine to land, and we can modify it if/when there's more discussion off thread? Approving since nobody else did :)

[MyDeveloperDay]

llvm/docs/Proposals/VariableNames.rst

294 ↗

(On Diff #190413)

@michaelplatings I have identifier a number of issues

bugs.llvm.org/PR41119  - [clang-tidy] readability-identifier-naming incorrectly fixes lambda capture
bugs.llvm.org/PR41120  - [clang-tidy] readability-identifier-naming incorrectly fixes variables which become keywords
      (previously call out here with regards to Int being renamed to int)
bugs.llvm.org/PR41122 - [clang-tidy] readability-identifier-naming misses fixing member variables in destructor

(and there could likely me more)

Which would need to be fixed in clang-tidy prior to any rename activity to prevent this process being painful. I think this is a good dog fooding opportunity for clang-tidy.

[michaelplatings]

llvm/docs/Proposals/VariableNames.rst

86 ↗

(On Diff #190413)

Yes, some kind of poll. Exactly how we do this is to be decided. @Charusso has pointed out https://reviews.llvm.org/vote/ but as we in the UK are painfully aware right now, giving people binary choices can lead to no choice at all. I'm inclined to copy Debian's voting method: https://www.debian.org/vote/
How we weight the voting is another interesting question. You could say more contributions = more weight, but given that we're specifically interested in the views of newcomers here that doesn't really work. On the other hand, 1 vote per person would mean that one person could get all their friends to vote for them which is even worse. Potentially we could give 1 vote to any person who has contributed before the discussion started.

141 ↗

(On Diff #190413)

I don't think that having a blessed list of acronyms is a good idea. It's going to be entirely dependent on the context

If an acronym is entirely dependent on the context then I suggest it shouldn't be on the list.

Part of my hope with this list is to be able to say "learn these acronyms and you should be well placed to read most code in LLVM". At the moment the code has too many variables with long scope named using acronyms that may have any number of meanings.

I take your point about names with short scope. If a tool is developed to expand acronyms then it should avoid touching names whose scope is only a few lines.

294 ↗

(On Diff #190413)

Thanks, I've added that to the proposal.

[Charusso]

llvm/docs/Proposals/VariableNames.rst

86 ↗

(On Diff #190413)

There you could fill 10 different options on-the-fly: https://reviews.llvm.org/vote/create/ and that is the common place across all the sub-projects. Immediately you could check-out this weight idea of a contributor. I see no problem with that.

llvm/trunk/docs/Proposals/VariableNames.rst

+===================
+Variable Names Plan
+===================
+
+.. contents::
+   :local:
+
+This plan is *provisional*. It is not agreed upon. It is written with the
+intention of capturing the desires and concerns of the LLVM community, and
+forming them into a plan that can be agreed upon.
+The original author is somewhat naïve in the ways of LLVM so there will
+inevitably be some details that are flawed. You can help - you can edit this
+page (preferably with a Phabricator review for larger changes) or reply to the
+`Request For Comments thread
+<http://lists.llvm.org/pipermail/llvm-dev/2019-February/130083.html>`_.
+
+Too Long; Didn't Read
+=====================
+
+Improve the readability of LLVM code.
+
+Introduction
+============
+
+The current `variable naming rule
+<../CodingStandards.html#name-types-functions-variables-and-enumerators-properly>`_
+states:
+
+  Variable names should be nouns (as they represent state). The name should be
+  camel case, and start with an upper case letter (e.g. Leader or Boats).
+
+This rule is the same as that for type names. This is a problem because the
+type name cannot be reused for a variable name [*]_. LLVM developers tend to
+work around this by either prepending ``The`` to the type name::
+
+  Triple TheTriple;
+
+... or more commonly use an acronym, despite the coding standard stating "Avoid
+abbreviations unless they are well known"::
+
+  Triple T;
+
+The proliferation of acronyms leads to hard-to-read code such as `this
+<https://github.com/llvm/llvm-project/blob/0a8bc14ad7f3209fe702d18e250194cd90188596/llvm/lib/Transforms/Vectorize/LoopVectorize.cpp#L7445>`_::
+
+  InnerLoopVectorizer LB(L, PSE, LI, DT, TLI, TTI, AC, ORE, VF.Width, IC,
+                         &LVL, &CM);
+
+Many other coding guidelines [LLDB]_ [Google]_ [WebKit]_ [Qt]_ [Rust]_ [Swift]_
+[Python]_ require that variable names begin with a lower case letter in contrast
+to class names which begin with a capital letter. This convention means that the
+most readable variable name also requires the least thought::
+
+  Triple triple;
+
+There is some agreement that the current rule is broken [LattnerAgree]_
+[ArsenaultAgree]_ [RobinsonAgree]_ and that acronyms are an obstacle to reading
+new code [MalyutinDistinguish]_ [CarruthAcronym]_ [PicusAcronym]_. There are
+some opposing views [ParzyszekAcronym2]_ [RicciAcronyms]_.
+
+This work-in-progress proposal is to change the coding standard for variable
+names to require that they start with a lower case letter.
+
+.. [*] In `some cases
+   <https://github.com/llvm/llvm-project/blob/8b72080d4d7b13072f371712eed333f987b7a18e/llvm/lib/CodeGen/SelectionDAG/SelectionDAG.cpp#L2727>`_
+   the type name *is* reused as a variable name, but this shadows the type name
+   and confuses many debuggers [DenisovCamelBack]_.
+
+Variable Names Coding Standard Options
+======================================
+
+There are two main options for variable names that begin with a lower case
+letter: ``camelBack`` and ``lower_case``. (These are also known by other names
+but here we use the terminology from clang-tidy).
+
+``camelBack`` is consistent with [WebKit]_, [Qt]_ and [Swift]_ while
+``lower_case`` is consistent with [LLDB]_, [Google]_, [Rust]_ and [Python]_.
+
+``camelBack`` is already used for function names, which may be considered an
+advantage [LattnerFunction]_ or a disadvantage [CarruthFunction]_.
+
+Approval for ``camelBack`` was expressed by [DenisovCamelBack]_
+[LattnerFunction]_ [IvanovicDistinguish]_.
+Opposition to ``camelBack`` was expressed by [CarruthCamelBack]_
+[TurnerCamelBack]_.
+Approval for ``lower_case`` was expressed by [CarruthLower]_
+[CarruthCamelBack]_ [TurnerLLDB]_.
+Opposition to ``lower_case`` was expressed by [LattnerLower]_.
+
+Differentiating variable kinds
+------------------------------
+
+An additional requested change is to distinguish between different kinds of
+variables [RobinsonDistinguish]_ [RobinsonDistinguish2]_ [JonesDistinguish]_
+[IvanovicDistinguish]_ [CarruthDistinguish]_ [MalyutinDistinguish]_.
+
+Others oppose this idea [HähnleDistinguish]_ [GreeneDistinguish]_
+[HendersonPrefix]_.
+
+A possibility is for member variables to be prefixed with ``m_`` and for global
+variables to be prefixed with ``g_`` to distinguish them from local variables.
+This is consistent with [LLDB]_. The ``m_`` prefix is consistent with [WebKit]_.
+
+A variation is for member variables to be prefixed with ``m``
+[IvanovicDistinguish]_ [BeylsDistinguish]_. This is consistent with [Mozilla]_.
+
+Another option is for member variables to be suffixed with ``_`` which is
+consistent with [Google]_ and similar to [Python]_. Opposed by
+[ParzyszekDistinguish]_.
+
+Reducing the number of acronyms
+===============================
+
+While switching coding standard will make it easier to use non-acronym names for
+new code, it doesn't improve the existing large body of code that uses acronyms
+extensively to the detriment of its readability. Further, it is natural and
+generally encouraged that new code be written in the style of the surrounding
+code. Therefore it is likely that much newly written code will also use
+acronyms despite what the coding standard says, much as it is today.
+
+As well as changing the case of variable names, they could also be expanded to
+their non-acronym form e.g. ``Triple T`` → ``Triple triple``.
+
+There is support for expanding many acronyms [CarruthAcronym]_ [PicusAcronym]_
+but there is a preference that expanding acronyms be deferred
+[ParzyszekAcronym]_ [CarruthAcronym]_.
+
+The consensus within the community seems to be that at least some acronyms are
+valuable [ParzyszekAcronym]_ [LattnerAcronym]_. The most commonly cited acronym
+is ``TLI`` however that is used to refer to both ``TargetLowering`` and
+``TargetLibraryInfo`` [GreeneDistinguish]_.
+
+The following is a list of acronyms considered sufficiently useful that the
+benefit of using them outweighs the cost of learning them. Acronyms that are
+either not on the list or are used to refer to a different type should be
+expanded.
+
+============================ =============
+Class name                   Variable name
+============================ =============
+DeterministicFiniteAutomaton dfa
+DominatorTree                dt
+LoopInfo                     li
+MachineFunction              mf
+MachineInstr                 mi
+MachineRegisterInfo          mri
+ScalarEvolution              se
+TargetInstrInfo              tii
+TargetLibraryInfo            tli
+TargetRegisterInfo           tri
+============================ =============
+
+In some cases renaming acronyms to the full type name will result in overly
+verbose code. Unlike most classes, a variable's scope is limited and therefore
+some of its purpose can implied from that scope, meaning that fewer words are
+necessary to give it a clear name. For example, in an optization pass the reader
+can assume that a variable's purpose relates to optimization and therefore an
+``OptimizationRemarkEmitter`` variable could be given the name ``remarkEmitter``
+or even ``remarker``.
+
+The following is a list of longer class names and the associated shorter
+variable name.
+
+========================= =============
+Class name                Variable name
+========================= =============
+BasicBlock                block
+ConstantExpr              expr
+ExecutionEngine           engine
+MachineOperand            operand
+OptimizationRemarkEmitter remarker
+PreservedAnalyses         analyses
+PreservedAnalysesChecker  checker
+TargetLowering            lowering
+TargetMachine             machine
+========================= =============
+
+Transition Options
+==================
+
+There are three main options for transitioning:
+
+1. Keep the current coding standard
+2. Laissez faire
+3. Big bang
+
+Keep the current coding standard
+--------------------------------
+
+Proponents of keeping the current coding standard (i.e. not transitioning at
+all) question whether the cost of transition outweighs the benefit
+[EmersonConcern]_ [ReamesConcern]_ [BradburyConcern]_.
+The costs are that ``git blame`` will become less usable; and that merging the
+changes will be costly for downstream maintainers. See `Big bang`_ for potential
+mitigations.
+
+Laissez faire
+-------------
+
+The coding standard could allow both ``CamelCase`` and ``camelBack`` styles for
+variable names [LattnerTransition]_.
+
+A code review to implement this is at https://reviews.llvm.org/D57896.
+
+Advantages
+**********
+
+ * Very easy to implement initially.
+
+Disadvantages
+*************
+
+ * Leads to inconsistency [BradburyConcern]_ [AminiInconsistent]_.
+ * Inconsistency means it will be hard to know at a guess what name a variable
+   will have [DasInconsistent]_ [CarruthInconsistent]_.
+ * Some large-scale renaming may happen anyway, leading to its disadvantages
+   without any mitigations.
+
+Big bang
+--------
+
+With this approach, variables will be renamed by an automated script in a series
+of large commits.
+
+The principle advantage of this approach is that it minimises the cost of
+inconsistency [BradburyTransition]_ [RobinsonTransition]_.
+
+It goes against a policy of avoiding large-scale reformatting of existing code
+[GreeneDistinguish]_.
+
+It has been suggested that LLD would be a good starter project for the renaming
+[Ueyama]_.
+
+Keeping git blame usable
+************************
+
+``git blame`` (or ``git annotate``) permits quickly identifying the commit that
+changed a given line in a file. After renaming variables, many lines will show
+as being changed by that one commit, requiring a further invocation of ``git
+blame`` to identify prior, more interesting commits [GreeneGitBlame]_
+[RicciAcronyms]_.
+
+**Mitigation**: `git-hyper-blame
+<https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/git-hyper-blame.html>`_
+can ignore or "look through" a given set of commits.
+A ``.git-blame-ignore-revs`` file identifying the variable renaming commits
+could be added to the LLVM git repository root directory.
+It is being `investigated
+<https://public-inbox.org/git/[e-mail]/>`_
+whether similar functionality could be added to ``git blame`` itself.
+
+Minimising cost of downstream merges
+************************************
+
+There are many forks of LLVM with downstream changes. Merging a large-scale
+renaming change could be difficult for the fork maintainers.
+
+**Mitigation**: A large-scale renaming would be automated. A fork maintainer can
+merge from the commit immediately before the renaming, then apply the renaming
+script to their own branch. They can then merge again from the renaming commit,
+resolving all conflicts by choosing their own version. This could be tested on
+the [SVE]_ fork.
+
+Provisional Plan
+================
+
+This is a provisional plan for the `Big bang`_ approach. It has not been agreed.
+
+#. Investigate improving ``git blame``. The extent to which it can be made to
+   "look through" commits may impact how big a change can be made.
+
+#. Write a script to expand acronyms.
+
+#. Experiment and perform dry runs of the various refactoring options.
+   Results can be published in forks of the LLVM Git repository.
+
+#. Consider the evidence and agree on the new policy.
+
+#. Agree & announce a date for the renaming of the starter project (LLD).
+
+#. Update the `policy page <../CodingStandards.html>`_. This will explain the
+   old and new rules and which projects each applies to.
+
+#. Refactor the starter project in two commits:
+
+   1. Add or change the project's .clang-tidy to reflect the agreed rules.
+      (This is in a separate commit to enable the merging process described in
+      `Minimising cost of downstream merges`_).
+      Also update the project list on the policy page.
+   2. Apply ``clang-tidy`` to the project's files, with only the
+      ``readability-identifier-naming`` rules enabled. ``clang-tidy`` will also
+      reformat the affected lines according to the rules in ``.clang-format``.
+      It is anticipated that this will be a good dog-fooding opportunity for
+      clang-tidy, and bugs should be fixed in the process, likely including:
+
+        * `readability-identifier-naming incorrectly fixes lambda capture
+          <https://bugs.llvm.org/show_bug.cgi?id=41119>`_.
+        * `readability-identifier-naming incorrectly fixes variables which
+          become keywords <https://bugs.llvm.org/show_bug.cgi?id=41120>`_.
+        * `readability-identifier-naming misses fixing member variables in
+          destructor <https://bugs.llvm.org/show_bug.cgi?id=41122>`_.
+
+#. Gather feedback and refine the process as appropriate.
+
+#. Apply the process to the following projects, with a suitable delay between
+   each (at least 4 weeks after the first change, at least 2 weeks subsequently)
+   to allow gathering further feedback.
+   This list should exclude projects that must adhere to an externally defined
+   standard e.g. libcxx.
+   The list is roughly in chronological order of renaming.
+   Some items may not make sense to rename individually - it is expected that
+   this list will change following experimentation:
+
+   * TableGen
+   * llvm/tools
+   * clang-tools-extra
+   * clang
+   * ARM backend
+   * AArch64 backend
+   * AMDGPU backend
+   * ARC backend
+   * AVR backend
+   * BPF backend
+   * Hexagon backend
+   * Lanai backend
+   * MIPS backend
+   * NVPTX backend
+   * PowerPC backend
+   * RISC-V backend
+   * Sparc backend
+   * SystemZ backend
+   * WebAssembly backend
+   * X86 backend
+   * XCore backend
+   * libLTO
+   * Debug Information
+   * Remainder of llvm
+   * compiler-rt
+   * libunwind
+   * openmp
+   * parallel-libs
+   * polly
+   * lldb
+
+#. Remove the old variable name rule from the policy page.
+
+#. Repeat many of the steps in the sequence, using a script to expand acronyms.
+
+References
+==========
+
+.. [LLDB] LLDB Coding Conventions https://llvm.org/svn/llvm-project/lldb/branches/release_39/www/lldb-coding-conventions.html
+.. [Google] Google C++ Style Guide https://google.github.io/styleguide/cppguide.html#Variable_Names
+.. [WebKit] WebKit Code Style Guidelines https://webkit.org/code-style-guidelines/#names
+.. [Qt] Qt Coding Style https://wiki.qt.io/Qt_Coding_Style#Declaring_variables
+.. [Rust] Rust naming conventions https://doc.rust-lang.org/1.0.0/style/style/naming/README.html
+.. [Swift] Swift API Design Guidelines https://swift.org/documentation/api-design-guidelines/#general-conventions
+.. [Python] Style Guide for Python Code https://www.python.org/dev/peps/pep-0008/#function-and-variable-names
+.. [Mozilla] Mozilla Coding style: Prefixes https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Coding_Style#Prefixes
+.. [SVE] LLVM with support for SVE https://github.com/ARM-software/LLVM-SVE
+.. [AminiInconsistent] Mehdi Amini, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130329.html
+.. [ArsenaultAgree] Matt Arsenault, http://lists.llvm.org/pipermail/llvm-dev/2019-February/129934.html
+.. [BeylsDistinguish] Kristof Beyls, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130292.html
+.. [BradburyConcern] Alex Bradbury, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130266.html
+.. [BradburyTransition] Alex Bradbury, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130388.html
+.. [CarruthAcronym] Chandler Carruth, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130313.html
+.. [CarruthCamelBack] Chandler Carruth, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130214.html
+.. [CarruthDistinguish] Chandler Carruth, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130310.html
+.. [CarruthFunction] Chandler Carruth, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130309.html
+.. [CarruthInconsistent] Chandler Carruth, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130312.html
+.. [CarruthLower] Chandler Carruth, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130430.html
+.. [DasInconsistent] Sanjoy Das, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130304.html
+.. [DenisovCamelBack] Alex Denisov, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130179.html
+.. [EmersonConcern] Amara Emerson, http://lists.llvm.org/pipermail/llvm-dev/2019-February/129894.html
+.. [GreeneDistinguish] David Greene, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130425.html
+.. [GreeneGitBlame] David Greene, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130228.html
+.. [HendersonPrefix] James Henderson, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130465.html
+.. [HähnleDistinguish] Nicolai Hähnle, http://lists.llvm.org/pipermail/llvm-dev/2019-February/129923.html
+.. [IvanovicDistinguish] Nemanja Ivanovic, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130249.html
+.. [JonesDistinguish] JD Jones, http://lists.llvm.org/pipermail/llvm-dev/2019-February/129926.html
+.. [LattnerAcronym] Chris Lattner, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130353.html
+.. [LattnerAgree] Chris Latter, http://lists.llvm.org/pipermail/llvm-dev/2019-February/129907.html
+.. [LattnerFunction] Chris Lattner, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130630.html
+.. [LattnerLower] Chris Lattner, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130629.html
+.. [LattnerTransition] Chris Lattner, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130355.html
+.. [MalyutinDistinguish] Danila Malyutin, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130320.html
+.. [ParzyszekAcronym] Krzysztof Parzyszek, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130306.html
+.. [ParzyszekAcronym2] Krzysztof Parzyszek, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130323.html
+.. [ParzyszekDistinguish] Krzysztof Parzyszek, http://lists.llvm.org/pipermail/llvm-dev/2019-February/129941.html
+.. [PicusAcronym] Diana Picus, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130318.html
+.. [ReamesConcern] Philip Reames, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130181.html
+.. [RicciAcronyms] Bruno Ricci, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130328.html
+.. [RobinsonAgree] Paul Robinson, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130111.html
+.. [RobinsonDistinguish] Paul Robinson, http://lists.llvm.org/pipermail/llvm-dev/2019-February/129920.html
+.. [RobinsonDistinguish2] Paul Robinson, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130229.html
+.. [RobinsonTransition] Paul Robinson, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130415.html
+.. [TurnerCamelBack] Zachary Turner, https://reviews.llvm.org/D57896#1402264
+.. [TurnerLLDB] Zachary Turner, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130213.html
+.. [Ueyama] Rui Ueyama, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130435.html

llvm/trunk/docs/index.rst

 can be better.
 
 .. toctree::
    :hidden:
 
    CodeOfConduct
    Proposals/GitHubMove
    Proposals/TestSuite
+   Proposals/VariableNames
    Proposals/VectorizationPlan
 
 :doc:`CodeOfConduct`
    Proposal to adopt a code of conduct on the LLVM social spaces (lists, events,
    IRC, etc).
 
 :doc:`Proposals/GitHubMove`
    Proposal to move from SVN/Git to GitHub.
 
 :doc:`Proposals/TestSuite`
    Proposals for additional benchmarks/programs for llvm's test-suite.
 
+:doc:`Proposals/VariableNames`
+   Proposal to change the variable names coding standard.
+
 :doc:`Proposals/VectorizationPlan`
    Proposal to model the process and upgrade the infrastructure of LLVM's Loop Vectorizer.
 
 Indices and tables
 ==================
 
 * :ref:`genindex`
 * :ref:`search`