[LLVMdev] draft rule for naming types/functions/variables

[Zhanyong Wan (λx.x x)]

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

> 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