[LLVMdev] RFC: variable names

[Sean Silva]

On Mon, Oct 13, 2014 at 5:46 PM, Philip Reames <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> wrote:
>
>>
>>   On Oct 13, 2014, at 4:31 PM, Chandler Carruth <chandlerc at google.com>
>> wrote:
>>
>>
>> On Mon, Oct 13, 2014 at 4:14 PM, Chandler Carruth <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?)

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.


> 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)?

-- 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         http://llvm.cs.uiuc.edu
>> http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev
>>
>>
>
>
> _______________________________________________
> LLVM Developers mailing listLLVMdev at cs.uiuc.edu         http://llvm.cs.uiuc.eduhttp://lists.cs.uiuc.edu/mailman/listinfo/llvmdev
>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20141013/74b2dbc2/attachment.html>