[LLVMdev] RFC: variable names

[Richard Smith]

On Mon, Oct 13, 2014 at 3:19 PM, Chandler Carruth <chandlerc at google.com>
wrote:

> On Mon, Oct 13, 2014 at 3:04 PM, Nick Kledzik <kledzik at apple.com> wrote:
>
>> I’d like to discuss revising the LLVM coding conventions to change the
>> naming of variables to start with a lowercase letter.
>>
>
> Almost all of your negatives of the current conventions also apply to your
> proposed convention.
>
> Type names: CamelCase
> Function names: camelCase
> Variable names: ???
>
> If we name variables in camelCase then variable names and function names
> collide.
>
> If we are going to change how we name variables, I very much want them to
> not collide with either type names or function names. My suggestion would
> be "lower_case" names.
>

I think this would be bad:

  function();
  lambda();
  longFunction();
  long_lambda();

... but possibly not in practice, since function names rarely have only one
word.

A partial-camel-case, partly-underscores convention sounds strange to me.
(I don't find this to be problematic for BIG_SCARY_MACROS and for
ABCK_EnumNamespaces because the former are rare and in the latter case the
underscore isn't a word separator, it's a namespace separator.) We have a
few people here who are used to such a style (since it's what the Google
style guide and derivatives uses); any useful feedback from that experience?


Some arguments against the change as proposed:

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.

2. The ambiguity introduced might be worse than the one removed. It's
usually easy to see if a name is a type or variable from the context of the
use. It's not so easy to see if a name is a function or a variable,
especially as more variables become callable due to the prevalence of
lambdas.

This also happens to be the vastly most common pattern across all C++
> coding styles and C-based language coding styles I have seen.
>
>
>>  This should not be a discussion on the pain of such a transition, or how
>> to get from here to there, but rather, if there is a better place to be.
>>
>> My arguments for the change are:
>>
>> 1. No other popular C++ coding style uses capitalized variable names.
>> For instance here are other popular C++ conventions that use camelCase:
>>
>>    http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml
>>
>
This does not use camelCase for variable names.

   http://www.c-xx.com/ccc/ccc.php
>>    http://geosoft.no/development/cppstyle.html
>>
>> And, of course, the all-lower-case conventions (e.g. C++ ARM) don’t
>> capitalize variable names.  In addition, all the common C derived languages
>> don’t use capitalized variable names (e.g. Java, C#, Objective-C).
>>
>
Some or all of those other conventions don't capitalize *any* names (other
than perhaps macros), so we're not going to become consistent with them by
making this change.

2. Ambiguity.  Capitalizing type names is common across most C++
>> conventions.  But in LLVM variables are also capitalized which conflates
>> types and variables.  Starting variable names with a lowercase letter
>> disambiguates variables from types. For instance, the following are
>> ambiguous using LLVM’s conventions:
>>
>> Xxx Yyy(Zzz);  // function prototype or local object construction?
>> Aaa(Bbb);      // function call or cast?
>>
>>
>> 3. Allows name re-use. Since types and variables are both nouns, using
>> different capitalization allows you to use the same simple name for types
>> and variables, for instance:
>>
>> Stream  stream;
>>
>>
>> 4. Dubious history.  Years ago the LLVM coding convention did not specify
>> if variables were capitalized or not.  Different contributors used
>> different styles.  Then in an effort to make the style more uniform,
>> someone flipped a coin and updated the convention doc to say variables
>> should be capitalized.  I never saw any on-list discussion about this.
>>
>
FWIW, I thought the argument for the current convention was: capitalize
proper nouns (classes and variables), do not capitalize verbs (functions),
as in English. Though maybe that's just folklore.

>
5. Momentum only.  When I’ve talked with various contributors privately, I
>> have found no one who says they likes capitalized variables.  It seems like
>> everyone thinks the conventions are carved in stone...
>>
>
Momentum is an argument against the change, not in favour of it: this
change has a re-learning cost for everyone who hacks on LLVM projects.
(Your point that no-one seems to like capitalized variables is valid, but
generally people are opposed to change too.)

I would add:

6. Lower barrier to entry. Our current convention is different from almost
all other C++ code, and new developers *very* frequently get it wrong.

My proposal is that we modify the LLVM Coding Conventions to have variable
>> names start with a lowercase letter.
>>
>> Index: CodingStandards.rst
>> ===================================================================
>> --- CodingStandards.rst (revision 219065)
>> +++ CodingStandards.rst (working copy)
>> @@ -1073,8 +1073,8 @@
>>    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``).
>>
>>  * **Function names** should be verb phrases (as they represent actions),
>> and
>>    command-like function should be imperative.  The name should be camel
>> case,
>>
>> _______________________________________________
>> 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 list
> 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/906b1292/attachment.html>