llvm dev - Nov 2010 - [LLVMdev] draft rule for naming types/functions/variables

+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

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.
I've made the change and uploaded the new patch to
http://codereview.appspot.com/3264041 -- you can also find it attached
to this message.  Thanks,
>
>> 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
>


-- 
Zhanyong
-------------- next part --------------
A non-text attachment was scrubbed...
Name: naming.patch
Type: application/octet-stream
Size: 3171 bytes
Desc: not available
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20101122/4c2bbdc8/attachment.obj>

Hi,
>    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.
I think there is a logical flaw in this argument: it doesn't matter if Ty is
not well-known in the wide world of programmers as long as it is well-known
inside LLVM: if "Ty" is used consistently all over the code base, then
I think
that's good enough.
> Good point.  Done.  Hopefully this doesn't bring on bike shedding. ;-)
It just did :)

Ciao,

Duncan.

Zhanyong Wan (λx.x x) wrote:
> 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.
>
I don't think this is natural at all.  :-)

When the rule is to select readable and descriptive names, using names 
that only differ in case seems non-optimal. What about tYpe, tyPe, or 
typE?


Bo Persson

On Tue, Nov 23, 2010 at 10:12 AM, Bo Persson <bop at gmb.dk>
wrote:
> Zhanyong Wan (λx.x x) wrote:
>
>> 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.
>>
>
> I don't think this is natural at all.  :-)
>
> When the rule is to select readable and descriptive names, using names
> that only differ in case seems non-optimal. What about tYpe, tyPe, or
> typE?
These are not allowed because they are not in camel case:
http://en.wikipedia.org/wiki/CamelCase
>
>
> Bo Persson
>
> _______________________________________________
> cfe-dev mailing list
> cfe-dev at cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev
>


-- 
Zhanyong

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

Hi,

I enjoyed the new coding style in recent patches. Camel case makes it easy
to pick a descriptive name. Starting functions and variables with lower
cases reduces chances to conflict with a type name.

2010/11/23 Zhanyong Wan (λx.x x) <wan at google.com>
> 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.
>
> I've made the change and uploaded the new patch to
> http://codereview.appspot.com/3264041 -- you can also find it attached
> to this message.  Thanks,
>
> >
> >> 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
> >
>
>
>
> --
> Zhanyong
>
> _______________________________________________
> 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/20101129/d72fad8a/attachment.html>