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

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>

> 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.
Honestly speaking, I don't. Especially in the cases when varname is
made from an
acronym. E.g. MachineInstr *MI looks much better than MachineInstr *mi, etc.

See latest Rafael's patch as an example.

-- 
With best regards, Anton Korobeynikov
Faculty of Mathematics and Mechanics, Saint Petersburg State University

On 29 nov 2010 03:47 "Xu Zhongxing" <xuzhongxing at gmail.com>
wrote:
> 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.
On the other hand, having names that only differ in the case of a single
character, is not really improving readability at all.

In my opinion, this is a misuse of the C family language rules that happen to
allow it. In other languages it is forbidden.


Bo Persson

> made from an
> acronym. E.g. MachineInstr *MI looks much better than MachineInstr *mi,
etc.
>
> See latest Rafael's patch as an example.
I am OK with handling acronyms differently from regular words. In
summary, the proposed names scheme would include variables names like
MI and PBQPStatistics but also registerPressure.

check?

Cheers,
Rafael

On Mon, Nov 29, 2010 at 8:02 AM, Anton Korobeynikov 
wrote:
>  MachineInstr *MI looks much better than MachineInstr *mi, etc.
Traditionally (in C), all-uppercase names have been reserved for
macros. Of course, real C++ programmers don't use macros... :)

Still, looking at an identifier e.g. FROM, it's not immediately clear
that it's not a macro but an instance of FastResponseOuterMethod.

-- 
GCS a+ e++ d- C++ ULS$ L+$ !E- W++ P+++$ w++$ tv+ b++ DI D++ 5++
Life is complex, with real and imaginary parts.
"Ok, it boots. Which means it must be bug-free and perfect. " -- Linus
Torvalds
"People disagree with me. I just ignore them." -- Linus Torvalds

On Sun, Nov 28, 2010 at 11:02 PM, Anton Korobeynikov
<anton at korobeynikov.info> wrote:
>> 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.
> Honestly speaking, I don't. Especially in the cases when varname is
> made from an
> acronym. E.g. MachineInstr *MI looks much better than MachineInstr *mi,
etc.
>
> See latest Rafael's patch as an example.
I think it's worthwhile to note that:

C++ is such a complex language that no single naming convention will
be able to cover all cases.  Therefore we aim at a reasonable default
that works for the majority of the cases.  As Chris put at the
beginning of the coding standards, "no coding standards should be
regarded as absolute requirements to be followed in all instances."
Exceptions can be made (although rarely) when truly needed.

Csaba has pointed out the problem of possible clash (at least
confusion) with macro names for variable names like MI.  I agree that
'mi' is not a great name either in this case.  In fact, it's not
even
camel case.  How about instr?  Or, perhaps a name that clarifies its
role (jumpInstr, nextInstr, etc)?  Or, if this is a short-lived local
variable, I'd be fine with 'mi'.

Cheers,
-- 
Zhanyong

On Mon, Nov 29, 2010 at 12:39 AM, Bo Persson <bop at gmb.dk>
wrote:
>
>
>
> On 29 nov 2010 03:47 "Xu Zhongxing" <xuzhongxing at
gmail.com> wrote:
>> 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.
>
> On the other hand, having names that only differ in the case of a single
character, is not really improving readability at all.
It depends on what you are comparing with, right?

'type' may or may not be a great name for a variable of type (no pun
intended) Type.  If this variable represents a generic value that can
be any Type, then 'type' might be as descriptive as you need it to be.
 Otherwise, you might want to pick names like operandType or
returnType, for example.  In any case, I don't think T, Ty, or AType
is more readable.
> In my opinion, this is a misuse of the C family language rules that happen
to allow it. In other languages it is forbidden.
Since changing the C++ language is not an option, we'll have to live
with its rules and conventions, rather than fighting them.  Note that
while some languages (e.g. Pascal) have case-insensitive identifiers,
not all non-C-family languages are like that.  For example, in
Haskell, the practice of uppercase names for types and lowercase names
for variables is not only preferred, but actually enforced by the
compiler.
-- 
Zhanyong

Besides the fact that mi is a horrible (non-descriptive) variable  
name, I far prefer mi over MI.

On Nov 29, 2010, at 1:02 AM, Anton Korobeynikov  
<anton at korobeynikov.info> wrote:
>> 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.
> Honestly speaking, I don't. Especially in the cases when varname is
> made from an
> acronym. E.g. MachineInstr *MI looks much better than MachineInstr  
> *mi, etc.
>
> See latest Rafael's patch as an example.
>
> -- 
> With best regards, Anton Korobeynikov
> Faculty of Mathematics and Mechanics, Saint Petersburg State  
> University
> _______________________________________________
> cfe-dev mailing list
> cfe-dev at cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev

On Mon, Nov 29, 2010 at 5:02 AM, Anton Korobeynikov
<anton at korobeynikov.info> wrote:
>> 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.
> Honestly speaking, I don't. Especially in the cases when varname is
> made from an
> acronym. E.g. MachineInstr *MI looks much better than MachineInstr *mi,
etc.
>
Hum? I don't think MI is better. I haven't see this style until
clang/llvm. Many others open source projects just uses the normal
lower case variable, which is MUCH better IMO.

For me is confusing to have a variable starting with captial letter,
because it's hard to differentiate it from class names.