[LLVMdev] RFC: variable names

Philip Reames listmail at philipreames.com
Mon Oct 13 18:08:08 PDT 2014 

On 10/13/2014 05:56 PM, Sean Silva wrote:
>
>
> On Mon, Oct 13, 2014 at 5:46 PM, Philip Reames 
> <listmail at philipreames.com <mailto:listmail at philipreames.com>> wrote:
>
>
>     On 10/13/2014 05:23 PM, Sean Silva wrote:
>>
>>
>>     On Mon, Oct 13, 2014 at 5:09 PM, Jim Grosbach <grosbach at apple.com
>>     <mailto:grosbach at apple.com>> wrote:
>>
>>
>>>         On Oct 13, 2014, at 4:31 PM, Chandler Carruth
>>>         <chandlerc at google.com <mailto:chandlerc at google.com>> wrote:
>>>
>>>
>>>         On Mon, Oct 13, 2014 at 4:14 PM, Chandler Carruth
>>>         <chandlerc at google.com <mailto:chandlerc at google.com>> wrote:
>>>
>>>                 1. Initialisms. It's common in Clang code (also in
>>>                 LLVM?) to use initialisms as variable names. This
>>>                 doesn't really seem to work for names that start
>>>                 with a lower case letter.
>>>
>>>
>>>             I think wee at least need a good answer to this.
>>>
>>>
>>>         As I really suspect this is the most important point to
>>>         address, let me make an attempt:
>>>
>>>         Variable names are *either* initialisms, written as all
>>>         caps, or terms written in lower case and separated by
>>>         underscores. For the purposes of variable naming "terms" can
>>>         include words but also extremely common and recognizable
>>>         abbreviations within LLVM such as "rhs", "lhs", or "gep".
>>>         These types of terms should not be written as initialisms
>>>         but as words. For example, you might write "LE" or
>>>         "lhs_expr" for the Left-hand Expression, but not "LHSE" or
>>>         "LHS_expr".
>>>
>>>         While I'm trying to avoid it, this has the advantage of
>>>         leaving a large number of initialisms in the existing code
>>>         base as "stylish".
>>>
>>>
>>>         I'm not really happy with this rule, but it is the least
>>>         disruptive and most consistent I can come up with. I would
>>>         also be happy encouraging people to not use initialisms
>>>         excessively or if confusing. I think the current codebase
>>>         uses them more than is helpful.
>>
>>         This makes sense to me. I think it strikes a good balance
>>         between updating our conventions to be better and also
>>         reflecting common in-practice usage patterns.
>>
>>
>>     This convention sounds like it would cause people to have to be
>>     constantly asking themselves "is this common enough to be an
>>     initialism-as-word or not?". The thing that started this
>>     conversation was someone complaining about going between
>>     codebases that they weren't sure whether to capitalize; now that
>>     person will have to get a feel for the local
>>     initialism-as-word's, which is a much greater burden than just
>>     the naming convention.
>>
>>     -- Sean Silva
>     In practice, you have to set such a threshold somewhere. 
>     Otherwise, you end up not being able to use terms like SSA, or Phi
>     without an explanation.  My view is that common initialisms like
>     lhs, gep, and dt should be accepted.  If you haven't spent enough
>     time in the code to recognize them, you probably shouldn't have
>     commit rights anyways.
>
>
> FWIW I don't know what dt means here (dominator tree? debug type?)
I was going for dominator tree and the actual common pattern is "DT".  I 
mistyped.
>
> Remember, one of the gripes about the current convention is that it is 
> a turn-off for people new to LLVM development (which often means not 
> that knowledgable about compilers). Thus "you probably shouldn't have 
> commit rights anyways" is an extremely counter-productive way to think 
> about this.
It could be viewed that way, yes. However, I also feel it's entirely 
reasonable to expect someone to know something about the code they're 
modifying.  Our objective is *not* to attract every possible 
submission.  It's to attract patches of reasonable quality, which don't 
impose undue review burden, and align with the overall direction of the 
project.

I'll note I'm a fairly recently contributor myself.  Did I find some of 
the code a bit confusing at times?  Yes.  But that was very rarely due 
to variable naming and more due to not knowing the baked in assumptions 
in the code.  While we can (and should) try to minimize startup cost, 
avoiding it entirely is nearly impossible and imposes a burden of effort 
on current developers which is not reasonable.

IMHO, we should optimize naming and similiar conventions for folks who 
are likely contributors.  Someone with no knowledge of compilers is not 
a likely contributor.  That's just a fact of life.  (I'm not saying no 
such person could every be a contributor, just that the effort required 
is well beyond that of learning a new coding convention.)
>
>
>     I am in favor of keeping that list of initialisms small.  Adding a
>     new one (either for an area, or the project as a whole) should
>     trigger discussion outside of a single review thread.
>
>
> This sounds like a strict increase in the amount of thinking about 
> pointless things that I have to do when coming up with a variable 
> name. Currently I only have to think about where my current file is. 
> Now you are suggesting that I should have to think about whether 
> something is common enough or not (which is actually real "AI 
> Complete" thinking)?
If it's in the file, it's clearly already met the standard I put forth.  
(Or it's being removed incrementally and review will catch it.)  I don't 
see this as being a major concern.

p.s. I have no idea what you mean by AI complete thinking in this context.
>
> -- Sean Silva
>
>
>
>     Philip
>>
>>
>>>         FWIW, I think that having different naming conventions for
>>>         data members and local variables has become essentially
>>>         untenable with lambdas and capture.
>>
>>         Can you elaborate a bit more on this? Maybe an example or two.
>>
>>         I’m very supportive of the general direction of all of this.
>>         Glad to see the general consensus developing.
>>
>>         -Jim
>>
>>
>>         _______________________________________________
>>         LLVM Developers mailing list
>>         LLVMdev at cs.uiuc.edu <mailto:LLVMdev at cs.uiuc.edu>
>>         http://llvm.cs.uiuc.edu
>>         http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev
>>
>>
>>
>>
>>     _______________________________________________
>>     LLVM Developers mailing list
>>     LLVMdev at cs.uiuc.edu  <mailto:LLVMdev at cs.uiuc.edu>          http://llvm.cs.uiuc.edu
>>     http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev
>
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20141013/c5fb10c3/attachment.html>

More information about the llvm-dev mailing list