[LLVMdev] [cfe-dev] draft rule for naming types/functions/variables

[Manuel Klimek]

On Mon, Nov 22, 2010 at 11:41 PM, Zhanyong Wan (λx.x x) <wan at google.com> wrote:
> +llvmdev
>
> Thanks for the comments, Chris.
>
> On Mon, Nov 22, 2010 at 11:08 PM, Chris Lattner <clattner at apple.com> wrote:
>>
>> On Nov 22, 2010, at 5:16 PM, Zhanyong Wan (λx.x x) wrote:
>>
>>> Hi guys,
>>>
>>> Based on our discussion last week, I put together a new coding style
>>> rule regarding the naming of types/functions/variables.  I've uploaded
>>> the patch to
>>>
>>> http://codereview.appspot.com/3264041
>>>
>>> Please let me know what you think.  My idea is to start with something
>>> non-controversial such that we can get the baseline committed soon.
>>> We can then tweak the rule as needed later to cover more specific
>>> scenarios.  Thanks,
>>
>> I think that the type/function name convention makes sense.
>>
>> However, I don't fully agree for local variable names.  For them, there are two cases, things with small lifetimes where having a simple short name is good, and things with longer lifetimes where you want something descriptive.
>>
>> For example, naming a variable i here is perfectly fine:
>>
>> for (unsigned i = 0; i != 100; ++i)
>>  A[i] = 0;
>>
>> Naming it "ArrayIndex" would not make it more clear :)
>
> Good point.  I actually have this in the example:
>
>  828   VehicleMaker m;  // Bad (abbreviation and non-descriptive); might be
>  829                    // OK for a local variable if its role is obvious.
>
> I'll reword the rule to match what you have in mind.
>
>> For capitalization, I generally prefer capital names with the exception being one character names that are often metasyntactic names (like i/j).
>
> If possible, I'd prefer that all variable names have the same style.
> I'm afraid that we'll end up with the current inconsistent style if we
> leave it to people to interpret whether a name is metasyntactic and
> thus should be lower-case.
>
> Also, having both types and variables in StrictCamelCase increases the
> chance of clashing between the two and thus sometimes makes it hard to
> choose good variable names.  For example, if you have a function that
> takes a Type parameter, how would you name the parameter if it has to
> start with an upper-case?  There are several obvious choices:
>
>  void VisitType(Type T);  // Bad -- T is too generic and could be
> mistaken for "temporary".
>  void VisitType(Type Ty);  // Bad -- Ty is not a well-known abbreviation.
>  void VisitType(Type AType);  // Unnecessarily awkward.
>
> In contrast,
>
>  void VisitType(Type type);
>
> is readable and natural.  The same argument applies to other kinds of variables.
>
> Another reason for preferring lower-case-started variable names is, as
> I wrote in the proposed rule, it helps a lot with readability to know
> at a glance whether something is a type or not -- at least that's my
> experience.
>
> So, would you be fine with making all variables start with lower-case?

Being new to the clang code base I can add my experience from the
patch I implemented.

Especially for somebody new to the code, getting to interpret "P" and
"PP" correctly depending on the context you're in makes it really hard
to follow the code in many places. And if you have a variable of type
"Parser" what else do you call it? I fully expect that you will be
able to read the code just fine if you're a full time developer
spending all your time in the code base. For contributions by people
using the code, who are finding bugs or missing features, "first
time"-readability can greatly reduce the time needed to write a patch
though.

If there's one thing I could wish for in the clang style, it would be
a differentiation in style between variables and types.

Cheers,
/Manuel

>> Also, since this applies to LLVM as a whole, I'd suggest moving this to llvmdev, which will reach a larger audience.
>
> Good point.  Done.  Hopefully this doesn't bring on bike shedding. ;-)
>
> --
> Zhanyong
>
> _______________________________________________
> cfe-dev mailing list
> cfe-dev at cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev