Variable names rule

[michaelplatings]

Summary

Following discussion and general agreement that the current naming rule for variables is not ideal, this patch switches the naming rule to make lowerCamelCase the standard, consistent with a prior RFC.

Given that over 450,000 variables are currently named in UpperCamelCase, the rule also permits using that form for consistency with existing code. I can't see a way to express that in .clang-tidy files.

[lebedev.ri]

Pretty sure this patch should have gone to llvm-commits, not cfe-commits.

[michaelplatings]

In D57896#1389042, @lebedev.ri wrote:

Pretty sure this patch should have gone to llvm-commits, not cfe-commits.

I just set the repository, Phabricator did the rest - apparently the magic isn't working so well.

[lebedev.ri]

In D57896#1389046, @michaelplatings wrote:

In D57896#1389042, @lebedev.ri wrote:

Pretty sure this patch should have gone to llvm-commits, not cfe-commits.

I just set the repository, Phabricator did the rest - apparently the magic isn't working so well.

1. Does clang-tidy warn on every single existing variable now?
2. It might be best to give this more visibility, by submitting a mail to llvm-dev, with a noticeable subject, like "RFC: changing variable naming rules in LLVM codebase"

[probinson]

In D57896#1389067, @lebedev.ri wrote:

2. It might be best to give this more visibility, by submitting a mail to llvm-dev, with a noticeable subject, like "RFC: changing variable naming rules in LLVM codebase"

+1. I know the discussion took place there originally, but "RFC" will catch more people's eyes. Also the prior discussion had some digressions (ahem) which a new RFC can be more focused.

[MyDeveloperDay]

does the readability-identifier-naming check need to be changed to support multiple allowed case types?

- key:             readability-identifier-naming.VariableCase
    value:        camelBack,CamelBack

[hubert.reinterpretcast]

I am generally in favour of this direction.

[lattner]

I am very much +1 on this. That said, this isn't the sort of thing we just use patch review for. Please agitate a robust discussion about this on llvm-dev. :-)

[michaelplatings]

In D57896#1389067, @lebedev.ri wrote:

1. Does clang-tidy warn on every single existing variable now?
2. It might be best to give this more visibility, by submitting a mail to llvm-dev, with a noticeable subject, like "RFC: changing variable naming rules in LLVM codebase"

1. Pretty much. Previously clang-tidy gave 56,787 unique warnings. After this patch it gives 361,382 unique warnings. I personally would be happy to change the settings from camelBack to aNy_CasE.

2. Done: http://lists.llvm.org/pipermail/llvm-dev/2019-February/130083.html

[MyDeveloperDay]

I personally would be happy to change the settings from camelBack to aNy_CasE.

Should we come up with a new style? say UpperOrLowerCamelCase or camelBackOrCase , I don't mind going and doing that in the readability-identifier-naming check, given that I just wrote up all the Options for that check https://clang.llvm.org/extra/clang-tidy/checks/readability-identifier-naming.html in D56563: [clang-tidy] add options documentation to readability-identifier-naming checker

[zturner]

Is this actually any better? Whereas before we can’t differentiate type names and variable names, under this proposal we can’t differentiate type names and function names. So it seems a bit of “6 of 1, half dozen of another”

[hubert.reinterpretcast]

In D57896#1391611, @zturner wrote:

Is this actually any better? Whereas before we can’t differentiate type names and variable names, under this proposal we can’t differentiate type names and function names. So it seems a bit of “6 of 1, half dozen of another”

Perhaps you mistyped? The proposal does not change the status quo of either type names nor function names. If you mean that we can't differentiate variable names and function names, then it seems worthwhile to point out that the actual letters (not just the case of said letters) matter too. Whereas the guidelines state that types and variables should have names that are nouns, the guidelines state that functions should have names that are verb phrases.

[michaelplatings]

In D57896#1390517, @MyDeveloperDay wrote:

Should we come up with a new style? say UpperOrLowerCamelCase, I don't mind going and doing that in the readability-identifier-naming check, given that I just wrote up all the Options for that check https://clang.llvm.org/extra/clang-tidy/checks/readability-identifier-naming.html in D56563: [clang-tidy] add options documentation to readability-identifier-naming checker

Sounds good to me. I see that you've made D57966 a child of this issue, but we could swap the dependency around so that once your patch is applied I can update this patch to use camelBackOrCase.

[MyDeveloperDay]

Sounds good to me. I see that you've made D57966 a child of this issue, but we could swap the dependency around so that once your patch is applied I can update this patch to use camelBackOrCase.

I'm OK if we want to do that, but its very much a circular dependency, I don't want to land D57966: [clang-tidy] add camelBackOrCase casing style to readability-identifier-naming to support change to variable naming policy (if adopted), unless this whole variableName suggestion is accepted (which I think is a good idea).. I think your suggestion warrants being the driver, lets do the clang-tidy change and subsequent .clang-tidy changes on another revision post acceptance of both.

FWIW, I agree with the comments that the function name should be differentiated from the variable by the use of a verbs, I've spent too much time in my career grepping for the word type in code

Type type = type();

I think

Type type = getType();

or

Type objectType = getType();

adds some increased levels of clarity.

[rupprecht]

In D57896#1391925, @hubert.reinterpretcast wrote:

In D57896#1391611, @zturner wrote:

Is this actually any better? Whereas before we can’t differentiate type names and variable names, under this proposal we can’t differentiate type names and function names. So it seems a bit of “6 of 1, half dozen of another”

Perhaps you mistyped? The proposal does not change the status quo of either type names nor function names. If you mean that we can't differentiate variable names and function names, then it seems worthwhile to point out that the actual letters (not just the case of said letters) matter too. Whereas the guidelines state that types and variables should have names that are nouns, the guidelines state that functions should have names that are verb phrases.

There is still overlap, e.g. "process" can be a noun (a Linux process) or a verb (to process something)

I think it should also be pointed out there is not zero overhead -- it's not a lot (at least for native English speakers, which many LLVM developers are not), but determining if a word is a verb or a noun is harder than looking at the casing. Small, but worth observing.

A different convention, e.g. lower_case, avoids this. Personally, I'd prefer that, but I'm also fine with lowerCamelCase just so we can stop using UpperCamelCase.

llvm/docs/CodingStandards.rst

1194

It would be nice for this section to be expanded a bit, just to avoid inevitable code review churn, e.g. if I'm adding 50 lines to a 200 line file, am I allowed to change the existing var names elsewhere in the file or method, or is that outside the scope of my change? If I'm reviewing that patch, do I tell the author they have to be consistent and revert other changes? etc.

Is there any plan to use clang-tidy to do a global cleanup, or is this going to be a totally ad-hoc migration -- variables use the new scheme only when the code is updated?

[michaelplatings]

Update .clang-tidy files to use aNy_CasE until camelBackOrCase is available.
Add more guidance around acronyms.
Add more guidance around consistency with existing CamelCase variable names.
Change other code examples to camelBack.

[michaelplatings]

llvm/docs/CodingStandards.rst

1194

I've had a go at expanding it. Please let me know if you have other suggestions.

Is there any plan to use clang-tidy to do a global cleanup, or is this going to be a totally ad-hoc migration -- variables use the new scheme only when the code is updated?

The latter. Given that the code doesn't keep to the existing .clang-tidy rules I'm not optimistic that we could persuade code owners to start now. That's not to say it couldn't happen eventually, but my aim at this point in time is to make it easier to use good variable names and I don't want perfect to be the enemy of better.

[michaelplatings]

Changed recommendation for acronyms from lower case to upper case, as suggested by several responses to the RFC.

[miyuki]

llvm/docs/CodingStandards.rst

1065–1068

signed is a keyword, it can't be used as a variable name

[lattner]

Changed recommendation for acronyms from lower case to upper case, as suggested by several responses to the RFC.

I haven't been following the discussion closely - why is this the preferred direction? I don't think that things like "Basicblock *bb" or "MachineInstr *mi" will be confusing, and going towards a consistently leading lower case letter seems simple and preferable.

-Chris

[michaelplatings]

In D57896#1402194, @lattner wrote:

Changed recommendation for acronyms from lower case to upper case, as suggested by several responses to the RFC.

I haven't been following the discussion closely - why is this the preferred direction? I don't think that things like "Basicblock *bb" or "MachineInstr *mi" will be confusing, and going towards a consistently leading lower case letter seems simple and preferable.

Maybe I misunderstood you (http://lists.llvm.org/pipermail/llvm-dev/2019-February/130223.html):

Maybe there should be an exception that variable names that start with an acronym still should start with an upper case letter?

That would also be fine with me - it could push such a debate down the road, and is definitely important for a transition period anyway.

Also Chandler (http://lists.llvm.org/pipermail/llvm-dev/2019-February/130313.html):

FWIW, I suspect separating the transition of our acronyms from the transition of identifiers with non-acronym words may be an effective way to chip away at the transition cost... Definitely an area that people who really care about this should look at carefully.

And Sanjoy (kind of) (http://lists.llvm.org/pipermail/llvm-dev/2019-February/130304.html):

maybe a gradual transition plan could be to allow these upper case acronyms for specific classes?

I agree that lower case acronyms would ultimately be more consistent, but given where we are it seems more achievable to only change the rule for non-acronyms.

[zturner]

In D57896#1402194, @lattner wrote:

Changed recommendation for acronyms from lower case to upper case, as suggested by several responses to the RFC.

I haven't been following the discussion closely - why is this the preferred direction? I don't think that things like "Basicblock *bb" or "MachineInstr *mi" will be confusing, and going towards a consistently leading lower case letter seems simple and preferable.

-Chris

I don’t think we should use this review as evidence of consensus. For example, I’m going to be against any change that doesn’t bring us closer to LLDB’s style of lower_case simply on the grounds that a move which brings us farther away from global consistency is strictly worse than one which brings us closer, despite ones personal aesthetic preferences.

And so far, I don’t really see that addressed here (or in the thread)

[zturner]

Since someone already accepted this, I suppose I should mark require changes to formalize my dissent

[MyDeveloperDay]

In D57896#1402280, @zturner wrote:

Since someone already accepted this, I suppose I should mark require changes to formalize my dissent

As it was Chris @lattner who accepted it, is your request for changes just based on the fact that it doesn't fit LLDB style?

I was trying to find where the LLDB coding style was documented but could only find this https://llvm.org/svn/llvm-project/lldb/branches/release_36/www/lldb-coding-conventions.html, seemingly this file has been move/removed around release 3.9.

But reading that link its seems unlikely to find a concencous between either naming conventions or formatting style between LLDB and the rest of LLVM, unless of course the solution would be to adopt LLDB style completely (for which I'd suspect there would be counter objections)

If that isn't a reality is blocking the rest of the LLVM community from relieving some of their eye strain an acceptable solution?

[zturner]

In D57896#1405334, @MyDeveloperDay wrote:

In D57896#1402280, @zturner wrote:

Since someone already accepted this, I suppose I should mark require changes to formalize my dissent

As it was Chris @lattner who accepted it, is your request for changes just based on the fact that it doesn't fit LLDB style?

(Side note, but I think everyones' opinions hold the same weight with regards to issues like this, and that is in part why changes like this are so difficult to move forward with. Because it takes a lot of consensus, not just one person, to drive a change.)

To answer your question: In a way, yes. To be clear, I don't actually care what the style we end up with is and I think arguing over which specific style we end up adopting is a silly argument. No style is going to be aesthetically pleasing to everyone, and I conjecture that any style we choose will have just as many people who dislike it as there are that like it. A coding style should serve exactly two purposes (in this order of importance): 1) Consistency across codebase, and 2) Visually distinguish semantically names that refer to semantically different things.

As long as it satisfies those two things, the specific choice of style is almost incosequential.

My objection is based on the fact adopting LLDB's style makes #1 significantly better at literally no incremental cost, while maintaining #2. So, the benefit of changing to literally any other style would be dwarfed by the benefit of changing to this particular style, because we would get instant consistency across a large swath of code.

If someone wants to propose a mass change of LLDB's names, I would actually be fine with that, but I suspect that will be just as difficult to drive, and so the path of least resistance here is to just use it and move on with our lives.

I was trying to find where the LLDB coding style was documented but could only find this https://llvm.org/svn/llvm-project/lldb/branches/release_36/www/lldb-coding-conventions.html, seemingly this file has been move/removed around release 3.9.

But reading that link its seems unlikely to find a concencous between either naming conventions or formatting style between LLDB and the rest of LLVM, unless of course the solution would be to adopt LLDB style completely (for which I'd suspect there would be counter objections)

If there are counter objections, I'd like to hear them. "I'm not a fan of that style" is not really a strong counter-objection in my opinion, because if we require a unanimous consensus on the most aesthetically pleasing style, I'm pretty sure nothing will ever happen. After all, I'm not a huge fan of LLDB's style myself. But as with any coding standard, you just deal with it.

If that isn't a reality is blocking the rest of the LLVM community from relieving some of their eye strain an acceptable solution?

Inconsistency is worse than eye strain, because it *causes* eye strain, as well as discourages people from contributing to the code at all. Anyone who has worked on both LLDB and LLVM can attest to how jarring the shift is moving back and forth between them, and that is a much more serious problem than a subset of developers who don't like something and another subset who do.

[MyDeveloperDay]

In D57896#1406336, @zturner wrote:

...

I can't argue with anything you say.. but I guess to reinforce your point introducing what is effectively a 3rd style would likely cause even more jarring...

The funny thing is this so reminds me of those religious bracketing style debates we had for decades.. then clang-format came along and I feel I stopped caring, I just let it do it for me on saving.. we need clang-tidy to do the same but for naming conventions.

[probinson]

In D57896#1406353, @MyDeveloperDay wrote:

I can't argue with anything you say.. but I guess to reinforce your point introducing what is effectively a 3rd style would likely cause even more jarring...

Zach isn't introducing a new style, the style already exists and is consistently used by what I think is our 3rd largest subproject. It happens not to be used at all by the two largest subprojects, but those subprojects already aren't consistent with themselves.
I would not mind a more concerted effort to migrate to whatever style we pick, which was notably lacking last time around. Then the jarring inconsistencies would go away, and we could all get back to complaining about content and not style.

[zturner]

In D57896#1406401, @probinson wrote:

In D57896#1406353, @MyDeveloperDay wrote:

I can't argue with anything you say.. but I guess to reinforce your point introducing what is effectively a 3rd style would likely cause even more jarring...

Zach isn't introducing a new style, the style already exists and is consistently used by what I think is our 3rd largest subproject. It happens not to be used at all by the two largest subprojects, but those subprojects already aren't consistent with themselves.
I would not mind a more concerted effort to migrate to whatever style we pick, which was notably lacking last time around. Then the jarring inconsistencies would go away, and we could all get back to complaining about content and not style.

If I read the post correctly, it was actually agreeing with me (because it said "to reinforce your point...". Meaning that something such as lowerCaseCamel would be the third style being referred to, while my proposal keeps the number of styles to 2. But, maybe I read it wrong. If I read it right, then obviously I agree :)

[MyDeveloperDay]

In D57896#1406407, @zturner wrote:

If I read the post correctly, it was actually agreeing with me (because it said "to reinforce your point...". Meaning that something such as lowerCaseCamel would be the third style being referred to

Correct! just acknowledging your point from a different perspective.

[probinson]

In D57896#1406412, @MyDeveloperDay wrote:

In D57896#1406407, @zturner wrote:

If I read the post correctly, it was actually agreeing with me (because it said "to reinforce your point...". Meaning that something such as lowerCaseCamel would be the third style being referred to

Correct! just acknowledging your point from a different perspective.

Doh! Sorry for the noise.

It looks like the RFC thread has mostly turned into a transition-plan debate, so should we work on the actual convention description here? Extracting the naming conventions from the 3.6-era link mentioned above, we have:

• types and classes are UpperCamelCase (this is unchanged from current LLVM style)
• methods are UpperCamelCase (this is also the old LLVM style IIRC)
• variables are snake_case
• static data members add "g_" prefix to variable style (although I see a proposal for "s_" instead)
• nonstatic data members add "m_" prefix to variable style

Did I miss anything really important?

[lattner]

I can understand Zach's position here, but LLDB has historically never conformed to the general LLVM naming or other conventions due to its heritage. It should not be taken as precedent that the rest of the project should follow.

In any case, I think that it is best for this discussion to take place on the llvm-dev list where it is likely to get the most visibility. Would you mind moving comments and discussions there?

[Charusso]

In D57896#1406812, @lattner wrote:

I can understand Zach's position here, but LLDB has historically never conformed to the general LLVM naming or other conventions due to its heritage. It should not be taken as precedent that the rest of the project should follow.

In any case, I think that it is best for this discussion to take place on the llvm-dev list where it is likely to get the most visibility. Would you mind moving comments and discussions there?

Hey! Random Clang developer is here after this topic became a little-bit dead as not everyone subbed to LLVM dev-list. I think the best solution for every difficult question is to let the users decide their own future among all the projects. I would announce polls (https://reviews.llvm.org/vote/) and announce them on every dev-list.

I do not see any better solution to decide if we would code like DRE, VD versus expr, decl as @lattner would code. And I am not sure if everyone happy with this_new_styling as @chandlerc and @zturner would code. E.g. I am not happy because I know my if-statements would take two lines of code instead of one and it would be super-duper-mega ugly and difficult to read. Here is an example:

static Optional<const llvm::APSInt *>
getConcreteIntegerValue(const Expr *CondVarExpr, const ExplodedNode *N) {
//...
  if (const auto *DRE = dyn_cast_or_null<DeclRefExpr>(CondVarExpr)) {
    if (const auto *VD = dyn_cast_or_null<VarDecl>(DRE->getDecl())) {
//...
}

would be:

static Optional<const llvm::APSInt *>                                           |
getConcreteIntegerValue(const Expr *cond_var_expr, const ExplodedNode *node) {  |
//...                                                                           |
  if (const auto *decl_ref_expr = dyn_cast_or_null<DeclRefExpr>(cond_var_expr)) {
    if (const auto *var_decl = dyn_cast_or_null<VarDecl>(decl_ref_expr->getDecl())) {
//...                                                                           |
}                                                             whoops column-81 ~^

Hungarian notation on members and globals are cool idea. However, the notation is made without the _ part, so I think mMember is better than m_member as we used to 80-column standard and it is waste of space and hurts your C-developer eyes. I would recommend b prefix to booleans as Unreal Engine 4 styling is used to do that (bIsCoolStyle) and it is handy. It is useful because booleans usually has multiple prefixes: has, have, is and you would list all the booleans together in autocompletion. Yes, there is a problem: if the notation is not capital like the pure Hungarian notation then it is problematic to list and we are back to the BIsCapitalLetter and MMember CamelCase-world where we started (except one project). I think @lattner could say if it is useful as all the Apple projects based on those notations and could be annoying.

[lattner]

In D57896#1434877, @Charusso wrote:

static Optional<const llvm::APSInt *>
getConcreteIntegerValue(const Expr *CondVarExpr, const ExplodedNode *N) {
//...

if (const auto *DRE = dyn_cast_or_null<DeclRefExpr>(CondVarExpr)) {
  if (const auto *VD = dyn_cast_or_null<VarDecl>(DRE->getDecl())) {

//...
}

would be:

static Optional<const llvm::APSInt *> |
getConcreteIntegerValue(const Expr *cond_var_expr, const ExplodedNode *node) { |
//... |

if (const auto *decl_ref_expr = dyn_cast_or_null<DeclRefExpr>(cond_var_expr)) {
  if (const auto *var_decl = dyn_cast_or_null<VarDecl>(decl_ref_expr->getDecl())) {

//... |
} whoops column-81 ~^

Hungarian notation on members and globals are cool idea. However, the notation is made without the `_` part, so I think `mMember` is better than `m_member` as we used to 80-column standard and it is waste of space and hurts your C-developer eyes. I would recommend `b` prefix to booleans as Unreal Engine 4 styling is used to do that (`bIsCoolStyle`) and it is handy. It is useful because booleans usually has multiple prefixes: `has, have, is` and you would list all the booleans together in autocompletion. Yes, there is a problem: if the notation is not capital like the pure Hungarian notation then it is problematic to list and we are back to the `BIsCapitalLetter` and `MMember` CamelCase-world where we started (except one project). I think @lattner could say if it is useful as all the Apple projects based on those notations and could be annoying.

FWIW, my suggestion is *not* to expand names like DRE to decl_ref_expr, I agree that doesn't add clarity to the code. Two possibilities: "dre", or "decl" which is what I would write today.

[Charusso]

In D57896#1435245, @lattner wrote:

FWIW, my suggestion is *not* to expand names like DRE to decl_ref_expr, I agree that doesn't add clarity to the code. Two possibilities: "dre", or "decl" which is what I would write today.

I totally agree with you, wherever I can I write that out for clarification. Please note that in my example there is two Expr and that is why I pointed out we need acronyms so we cannot really use expr and acronyms usually capital, that is why we went back to the default CamelCase standard. It was a little brainstorming and ping for you guys because I believe you would put those polls out and create a better code-base.

[sbc100]

Is there still appetite to land this change? We made the switch over in LLD a while back without any issues that I know of.

[michaelplatings]

Hi Sam, I won't be able to take this forward but you have my encouragement. To facilitate this change I got as far as changing Git [1], and GitHub has been updated accordingly [2], but I ran out of steam before getting to the change itself.
I'd be happy to let someone else (you?) take the lead and commandeer the change.

[1] https://moxio.com/blog/ignoring-bulk-change-commits-with-git-blame/
[2] https://github.blog/changelog/2022-03-24-ignore-commits-in-the-blame-view-beta/

[lattner]

I would also love to see this conceptually, but think it will be pretty polarizing in the community. It is worth another RFC thread before investing much time in it.

.clang-tidy

 Checks: '-*,clang-diagnostic-*,llvm-*,misc-*,-misc-unused-parameters,-misc-non-private-member-variables-in-classes,readability-identifier-naming'
 CheckOptions:
   - key:             readability-identifier-naming.ClassCase
     value:           CamelCase
   - key:             readability-identifier-naming.EnumCase
     value:           CamelCase
   - key:             readability-identifier-naming.FunctionCase
     value:           camelBack
   - key:             readability-identifier-naming.MemberCase
-    value:           CamelCase
+    value:           aNy_CasE
   - key:             readability-identifier-naming.ParameterCase
-    value:           CamelCase
+    value:           aNy_CasE
   - key:             readability-identifier-naming.UnionCase
     value:           CamelCase
   - key:             readability-identifier-naming.VariableCase
-    value:           CamelCase
+    value:           aNy_CasE
 

clang/.clang-tidy

 Checks: '-*,clang-diagnostic-*,llvm-*,misc-*,-misc-unused-parameters,-misc-non-private-member-variables-in-classes,-readability-identifier-naming'
 # Note that the readability-identifier-naming check is disabled, there are too
 # many violations in the codebase and they create too much noise in clang-tidy
 # results.
 # Naming settings are kept for documentation purposes and allowing to run the
 # check if the users would override this file, e.g. via a command-line arg.
 CheckOptions:
   - key:             readability-identifier-naming.ClassCase
     value:           CamelCase
   - key:             readability-identifier-naming.EnumCase
     value:           CamelCase
   - key:             readability-identifier-naming.FunctionCase
     value:           camelBack
   - key:             readability-identifier-naming.MemberCase
-    value:           CamelCase
+    value:           aNy_CasE
   - key:             readability-identifier-naming.ParameterCase
-    value:           CamelCase
+    value:           aNy_CasE
   - key:             readability-identifier-naming.UnionCase
     value:           CamelCase
   - key:             readability-identifier-naming.VariableCase
-    value:           CamelCase
+    value:           aNy_CasE
 

llvm/.clang-tidy

 Checks: '-*,clang-diagnostic-*,llvm-*,misc-*,-misc-unused-parameters,-misc-non-private-member-variables-in-classes,readability-identifier-naming'
 CheckOptions:
   - key:             readability-identifier-naming.ClassCase
     value:           CamelCase
   - key:             readability-identifier-naming.EnumCase
     value:           CamelCase
   - key:             readability-identifier-naming.FunctionCase
     value:           camelBack
   - key:             readability-identifier-naming.MemberCase
-    value:           CamelCase
+    value:           aNy_CasE
   - key:             readability-identifier-naming.ParameterCase
-    value:           CamelCase
+    value:           aNy_CasE
   - key:             readability-identifier-naming.UnionCase
     value:           CamelCase
   - key:             readability-identifier-naming.VariableCase
-    value:           CamelCase
+    value:           aNy_CasE
 

llvm/docs/CodingStandards.rst

 
 #. 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
    meaningful. For example, it's not clear what the parameter means in this call:
 
    .. code-block:: c++
 
-     Object.emitName(nullptr);
+     object.emitName(nullptr);
 
    An in-line C-style comment makes the intent obvious:
 
    .. code-block:: c++
 
-     Object.emitName(/*Prefix=*/nullptr);
+     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
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

 
 To describe function return value, start a new paragraph with the ``\returns``
 command.
 
 A minimal documentation comment:
 
 .. code-block:: c++
 
-  /// Sets the xyzzy property to \p Baz.
-  void setXyzzy(bool Baz);
+  /// Sets the xyzzy property to \p baz.
+  void setXyzzy(bool baz);
 
 A documentation comment that uses all Doxygen features in a preferred way:
 
 .. code-block:: c++
 
   /// Does foo and bar.
   ///
-  /// Does not do foo the usual way if \p Baz is true.
+  /// Does not do foo the usual way if \p baz is true.
   ///
   /// Typical usage:
   /// \code
-  ///   fooBar(false, "quux", Res);
+  ///   fooBar(false, "quux", res);
   /// \endcode
   ///
-  /// \param Quux kind of foo to do.
+  /// \param quux kind of foo to do.
   /// \param [out] Result filled with bar sequence on foo success.
   ///
   /// \returns true on success.
-  bool fooBar(bool Baz, StringRef Quux, std::vector<int> &Result);
+  bool fooBar(bool baz, StringRef quux, std::vector<int> &result);
 
 Don't duplicate the documentation comment in the header file and in the
 implementation file.  Put the documentation comments for public APIs into the
 header file.  Documentation comments for private APIs can go to the
 implementation file.  In any case, implementation files can include additional
 comments (not necessarily in Doxygen markup) to explain implementation details
 as needed.
 

 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:
 
 .. code-block:: c++
 
   foo({a, b, c}, {1, 2, 3});
 
-  llvm::Constant *Mask[] = {
+  llvm::Constant *mask[] = {
       llvm::ConstantInt::get(llvm::Type::getInt32Ty(getLLVMContext()), 0),
       llvm::ConstantInt::get(llvm::Type::getInt32Ty(getLLVMContext()), 1),
       llvm::ConstantInt::get(llvm::Type::getInt32Ty(getLLVMContext()), 2)};
 
 This formatting scheme also makes it particularly easy to get predictable,
 consistent, and automatic formatting with tools like `Clang Format`_.
 
 .. _Clang Format: https://clang.llvm.org/docs/ClangFormat.html

 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:
 
 .. code-block:: c++
 
-  if (V = getValue()) {
+  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:
 
 .. code-block:: c++
 
-  if ((V = getValue())) {
+  if ((v = getValue())) {
     ...
   }
 
 which shuts ``gcc`` up.  Any ``gcc`` warning that annoys you can be fixed by
 massaging the code appropriately.
 
 Write Portable Code
 ^^^^^^^^^^^^^^^^^^^

 * All declarations and definitions of a given ``class`` or ``struct`` must use
   the same keyword.  For example:
 
 .. code-block:: c++
 
   class Foo;
 
   // Breaks mangling in MSVC.
-  struct Foo { int Data; };
+  struct Foo { int data; };
 
 * As a rule of thumb, ``struct`` should be kept to structures where *all*
   members are declared public.
 
 .. code-block:: c++
 
   // Foo feels like a class... this is strange.
   struct Foo {
   private:
-    int Data;
+    int data;
   public:
-    Foo() : Data(0) { }
-    int getData() const { return Data; }
-    void setData(int D) { Data = D; }
+    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.
   struct Bar {
-    int Data;
-    Bar() : Data(0) { }
+    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
 *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);
+    Foo(int n);
 
     // ...
   };
 
   // The Foo constructor call is very deliberate, no braces.
   std::fill(foo.begin(), foo.end(), Foo("name"));
 
   // The pair is just being constructed like an aggregate, use braces.
-  bar_map.insert({my_key, my_value});
+  bar_map.insert({myKey, myValue});
 
 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};
 
 Use ``auto`` Type Deduction to Make Code More Readable

 expensive.
 
 As a rule of thumb, use ``auto &`` unless you need to copy the result, and use
 ``auto *`` when copying pointers.
 
 .. code-block:: c++
 
   // Typically there's no reason to copy.
-  for (const auto &Val : Container) { observe(Val); }
-  for (auto &Val : Container) { Val.change(); }
+  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); }
+  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(); }
+  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

 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:
 
 .. code-block:: c++
 
-  Value *doSomething(Instruction *I) {
-    if (!I->isTerminator() &&
-        I->hasOneUse() && doOtherThing(I)) {
+  Value *doSomething(Instruction *instruction) {
+    if (!instruction->isTerminator() &&
+        instruction->hasOneUse() && doOtherThing(instruction)) {
       ... some long code ....
     }
 
     return 0;
   }
 
 This code has several problems if the body of the ``'if'`` is large.  When
 you're looking at the top of the function, it isn't immediately clear that this
 *only* does interesting things with non-terminator instructions, and only
 applies to things with the other predicates.  Second, it is relatively difficult
 to describe (in comments) why these predicates are important because the ``if``
 statement makes it difficult to lay out the comments.  Third, when you're deep
 within the body of the code, it is indented an extra level.  Finally, when
 reading the top of the function, it isn't clear what the result is if the
 predicate isn't true; you have to read to the end of the function to know that
 it returns null.
 
 It is much preferred to format the code like this:
 
 .. code-block:: c++
 
-  Value *doSomething(Instruction *I) {
+  Value *doSomething(Instruction *instruction) {
     // Terminators never need 'something' done to them because ... 
-    if (I->isTerminator())
+    if (instruction->isTerminator())
       return 0;
 
     // We conservatively avoid transforming instructions with multiple uses
     // because goats like cheese.
-    if (!I->hasOneUse())
+    if (!instruction->hasOneUse())
       return 0;
 
     // This is really just here for example.
-    if (!doOtherThing(I))
+    if (!doOtherThing(instruction))
       return 0;
     
     ... some long code ....
   }
 
 This fixes these problems.  A similar problem frequently happens in ``for``
 loops.  A silly example is something like this:
 
 .. code-block:: c++
 
-  for (Instruction &I : BB) {
-    if (auto *BO = dyn_cast<BinaryOperator>(&I)) {
+  for (Instruction &instruction : BB) {
+    if (auto *BO = dyn_cast<BinaryOperator>(&instruction)) {
       Value *LHS = BO->getOperand(0);
       Value *RHS = BO->getOperand(1);
       if (LHS != RHS) {
         ...
       }
     }
   }
 
 When you have very, very small loops, this sort of structure is fine. But if it
 exceeds more than 10-15 lines, it becomes difficult for people to read and
 understand at a glance. The problem with this sort of code is that it gets very
 nested very quickly. Meaning that the reader of the code has to keep a lot of
 context in their brain to remember what is going immediately on in the loop,
 because they don't know if/when the ``if`` conditions will have ``else``\s etc.
 It is strongly preferred to structure the loop like this:
 
 .. code-block:: c++
 
-  for (Instruction &I : BB) {
-    auto *BO = dyn_cast<BinaryOperator>(&I);
+  for (Instruction &instruction : BB) {
+    auto *BO = dyn_cast<BinaryOperator>(&instruction);
     if (!BO) continue;
 
     Value *LHS = BO->getOperand(0);
     Value *RHS = BO->getOperand(1);
     if (LHS == RHS) continue;
 
     ...
   }

 For similar reasons 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*:
 
 .. code-block:: c++
 
   case 'J': {
-    if (Signed) {
-      Type = Context.getsigjmp_bufType();
-      if (Type.isNull()) {
-        Error = ASTContext::GE_Missing_sigjmp_buf;
+    if (isSigned) {
+      type = context.getsigjmp_bufType();
+      if (type.isNull()) {
+        error = ASTContext::GE_Missing_sigjmp_buf;
         return QualType();
       } else {
         break;
       }
     } else {
-      Type = Context.getjmp_bufType();
-      if (Type.isNull()) {
-        Error = ASTContext::GE_Missing_jmp_buf;
+      type = context.getjmp_bufType();
+      if (type.isNull()) {
+        error = ASTContext::GE_Missing_jmp_buf;
         return QualType();
       } else {
         break;
       }
     }
   }
 
 It is better to write it like this:
 
 .. code-block:: c++
 
   case 'J':
-    if (Signed) {
-      Type = Context.getsigjmp_bufType();
-      if (Type.isNull()) {
-        Error = ASTContext::GE_Missing_sigjmp_buf;
+    if (isSigned) {
+      type = context.getsigjmp_bufType();
+      if (type.isNull()) {
+        error = ASTContext::GE_Missing_sigjmp_buf;
         return QualType();
       }
     } else {
-      Type = Context.getjmp_bufType();
-      if (Type.isNull()) {
-        Error = ASTContext::GE_Missing_jmp_buf;
+      type = context.getjmp_bufType();
+      if (type.isNull()) {
+        error = ASTContext::GE_Missing_jmp_buf;
         return QualType();
       }
     }
     break;
 
 Or better yet (in this case) as:
 
 .. code-block:: c++
 
   case 'J':
-    if (Signed)
-      Type = Context.getsigjmp_bufType();
+    if (isSigned)
+      type = context.getsigjmp_bufType();
     else
-      Type = Context.getjmp_bufType();
+      type = context.getjmp_bufType();
     
-    if (Type.isNull()) {
-      Error = Signed ? ASTContext::GE_Missing_sigjmp_buf :
+    if (type.isNull()) {
+      error = isSigned ? ASTContext::GE_Missing_sigjmp_buf :
                        ASTContext::GE_Missing_jmp_buf;
       return QualType();
     }
     break;
 
 The idea is to reduce indentation and the amount of code you have to keep track
 of when reading the code.
               
 Turn Predicate Loops into Predicate Functions
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 It is very common to write small loops that just compute a boolean value.  There
 are a number of ways that people commonly write these, but an example of this
 sort of thing is:
 
 .. code-block:: c++
 
-  bool FoundFoo = false;
-  for (unsigned I = 0, E = BarList.size(); I != E; ++I)
-    if (BarList[I]->isFoo()) {
-      FoundFoo = true;
+  bool foundFoo = false;
+  for (unsigned i = 0, end = barList.size(); i != end; ++i)
+    if (barList[i]->isFoo()) {
+      foundFoo = true;
       break;
     }
 
-  if (FoundFoo) {
+  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:
 
 .. 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())
+  static bool containsFoo(const std::vector<Bar*> &list) {
+    for (unsigned i = 0, end = list.size(); i != end; ++i)
+      if (list[i]->isFoo())
         return true;
     return false;
   }
   ...
 
-  if (containsFoo(BarList)) {
+  if (containsFoo(barList)) {
     ...
   }
 
 There are many reasons for doing this: it reduces indentation and factors out
 code which can often be shared by other code that checks for the same predicate.
 More importantly, it *forces you to pick a name* for the function, and forces
 you to write a comment for it.  In this silly example, this doesn't add much
 value.  However, if the condition is complex, this can make it a lot easier for

 
 In general, names should be in camel case (e.g. ``TextFileReader`` and
 ``isLValue()``).  Different kinds of declarations have different rules:
 
 * **Type names** (including classes, structs, enums, typedefs, etc) should be
   nouns and start with an upper-case letter (e.g. ``TextFileReader``).
 
 * **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``).
-  
+  be camel case, and start with a lower case letter (e.g. ``leader`` or
+  ``boats``). Acronyms should be avoided unless well known, but if used they
+  should typically be upper case (e.g. ``TLI``).
+  It is acceptable, but not necessary, to use ``UpperCamelCase`` variable names
+  for consistency with existing code. If a code change renames an existing
+  variable, affecting multiple lines that wouldn't otherwise be touched by the
+  change, typically it is preferred to do the renaming in a separate patch to
+  keep the intent of functional changes clear.
 * **Function names** should be verb phrases (as they represent actions), and
   command-like function should be imperative.  The name should be camel case,
   and start with a lower case letter (e.g. ``openFile()`` or ``isFoo()``).
 
 * **Enum declarations** (e.g. ``enum Foo {...}``) are types, so they should
   follow the naming conventions for types.  A common use for enums is as a
   discriminator for a union, or an indicator of a subclass.  When an enum is
   used for something like this, it should have a ``Kind`` suffix

 (e.g. ``global_begin()`` and ``use_begin()``).
 
 Here are some examples of good and bad names:
 
 .. 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
-                                // kind of factories.
+    Factory<Tire> f;            // Bad -- abbreviation and non-descriptive.
+    Factory<Tire> factory;      // Better.
+    Factory<Tire> tireFactory;  // Even better -- if VehicleMaker has more than
+                                // one kind of factory.
   };
 
-  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.
+  Vehicle makeVehicle(VehicleType type) {
+    // Reusing the type name in lowerCamelCase form is often a good way to get
+    // a suitable variable name.
+    VehicleMaker vehicleMaker;
+
+    // Bad -- 'tmp1' provides no information.
+    Tire tmp1 = vehicleMaker.makeTire();
+
+    // Good -- descriptive.
+    Light headlight = vehicleMaker.makeLight("head");
     ...
   }
 
 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
 caught early by an assertion, which reduces debugging time dramatically.  The
 "``<cassert>``" header file is probably already included by the header files you
 are using, so it doesn't cost anything to use it.
 
 To further assist with debugging, make sure to put some kind of error message in
 the assertion statement, which is printed if the assertion is tripped. This
 helps the poor debugger make sense of why an assertion is being made and
 enforced, and hopefully what to do about it.  Here is one complete example:
 
 .. code-block:: c++
 
-  inline Value *getOperand(unsigned I) {
-    assert(I < Operands.size() && "getOperand() out of range!");
-    return Operands[I];
+  inline Value *getOperand(unsigned i) {
+    assert(i < operands.size() && "getOperand() out of range!");
+    return operands[I];
   }
 
 Here are more examples:
 
 .. code-block:: c++
 
-  assert(Ty->isPointerType() && "Can't allocate a non-pointer type!");
+  assert(type->isPointerType() && "Can't allocate a non-pointer type!");
 
-  assert((Opcode == Shl || Opcode == Shr) && "ShiftInst Opcode invalid!");
+  assert((opcode == SHL || opcode == SHR) && "ShiftInst Opcode invalid!");
 
   assert(idx < getNumSuccessors() && "Successor # out of range!");
 
-  assert(V1.getType() == V2.getType() && "Constant types must be identical!");
+  assert(v1.getType() == v2.getType() && "Constant types must be identical!");
 
-  assert(isa<PHINode>(Succ->front()) && "Only works on PHId BBs!");
+  assert(isa<PHINode>(succ->front()) && "Only works on PHId BBs!");
 
 You get the idea.
 
 In the past, asserts were used to indicate a piece of code that should not be
 reached.  These were typically of the form:
 
 .. code-block:: c++
 

 used instead. In cases where this is not practical, ``report_fatal_error`` may
 be used.
 
 Another issue is that values used only by assertions will produce an "unused
 value" warning when assertions are disabled.  For example, this code will warn:
 
 .. code-block:: c++
 
-  unsigned Size = V.size();
-  assert(Size > 42 && "Vector smaller than it should be");
+  unsigned size = v.size();
+  assert(size > 42 && "Vector smaller than it should be");
 
-  bool NewToSet = Myset.insert(Value);
-  assert(NewToSet && "The value shouldn't be in the set yet");
+  bool newToSet = myset.insert(Value);
+  assert(newToSet && "The value shouldn't be in the set yet");
 
 These are two interesting different cases. In the first case, the call to
 ``V.size()`` is only useful for the assert, and we don't want it executed when
 assertions are disabled.  Code like this should move the call into the assert
 itself.  In the second case, the side effects of the call must happen whether
 the assert is enabled or not.  In this case, the value should be cast to void to
 disable the warning.  To be specific, it is preferred to write the code like
 this:
 
 .. code-block:: c++
 
-  assert(V.size() > 42 && "Vector smaller than it should be");
+  assert(v.size() > 42 && "Vector smaller than it should be");
 
-  bool NewToSet = Myset.insert(Value); (void)NewToSet;
-  assert(NewToSet && "The value shouldn't be in the set yet");
+  bool newToSet = myset.insert(value); (void)newToSet;
+  assert(newToSet && "The value shouldn't be in the set yet");
 
 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;``".
 

 
 The introduction of range-based ``for`` loops in C++11 means that explicit
 manipulation of iterators is rarely necessary. We use range-based ``for``
 loops wherever possible for all newly added code. For example:
 
 .. code-block:: c++
 
   BasicBlock *BB = ...
-  for (Instruction &I : *BB)
-    ... use I ...
+  for (Instruction &instruction : *BB)
+    ... use instruction ...
 
 Don't evaluate ``end()`` every time through a loop
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 In cases where range-based ``for`` loops can't be used and it is necessary
 to write an explicit iterator-based loop, pay close attention to whether
 ``end()`` is re-evaluted on each loop iteration. One common mistake is to
 write a loop in this style:
 
 .. code-block:: c++
 
   BasicBlock *BB = ...
-  for (auto I = BB->begin(); I != BB->end(); ++I)
-    ... use I ...
+  for (auto i = BB->begin(); i != BB->end(); ++i)
+    ... use i ...
 
 The problem with this construct is that it evaluates "``BB->end()``" every time
 through the loop.  Instead of writing the loop like this, we strongly prefer
 loops to be written so that they evaluate it once before the loop starts.  A
 convenient way to do this is like so:
 
 .. code-block:: c++
 
   BasicBlock *BB = ...
-  for (auto I = BB->begin(), E = BB->end(); I != E; ++I)
-    ... use I ...
+  for (auto i = BB->begin(), end = BB->end(); i != end; ++i)
+    ... use i ...
 
 The observant may quickly point out that these two loops may have different
 semantics: if the container (a basic block in this case) is being mutated, then
 "``BB->end()``" may change its value every time through the loop and the second
 loop may not in fact be correct.  If you actually do depend on this behavior,
 please write the loop in the first form and add a comment indicating that you
 did it intentionally.
 
 Why do we prefer the second form (when correct)?  Writing the loop in the first
 form has two problems. First it may be less efficient than evaluating it at the
 start of the loop.  In this case, the cost is probably minor --- a few extra
 loads every time through the loop.  However, if the base expression is more
 complex, then the cost can rise quickly.  I've seen loops where the end
-expression was actually something like: "``SomeMap[X]->end()``" and map lookups
+expression was actually something like: "``someMap[x]->end()``" and map lookups
 really aren't cheap.  By writing it in the second form consistently, you
 eliminate the issue entirely and don't even have to think about it.
 
 The second (even bigger) issue is that writing the loop in the first form hints
 to the reader that the loop is mutating the container (a fact that a comment
 would handily confirm!).  If you write the loop in the second form, it is
 immediately obvious without even looking at the body of the loop that the
 container isn't being modified, which makes it easier to read the code and

 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
 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) ...
+  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);
+  a = foo(42, 92) + bar(X);
 
 and this is bad:
 
 .. 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);
+  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);
+  a = foo ((42, 92) + bar) (x);
 
 when skimming through the code.  By avoiding a space in a function, we avoid
 this misinterpretation.
 
 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
+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.