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

On Tue, Nov 30, 2010 at 5:07 PM, Chris Lattner <clattner at apple.com>
wrote:
>
> On Nov 30, 2010, at 5:02 PM, Zhanyong Wan (λx.x x) wrote:
>
>> Thanks for the comments, Chris!  Glad that we are making progress.
>>
>> I'll make most of the edits you suggested later today.  Before
that,
>> there are a couple of high-level points I'd like to go over with
you.
>>
>> 1. I totally agree that the biggest benefit of a naming convention is
>> uniform APIs.  On the other hand, an inconsistent local naming style
>> hurts the productivity of contributors and can lead to bugs by causing
>> confusion.  I'm fine with local variables having short names when
>> their scope is limited (say, fits within one screen) or their role is
>> obvious (like 'i' for an iterator), but I do find the context
>> switching annoying when I have to adjust for the different styles as I
>> move to different parts of the codebase.  Just something for you to
>> consider.
>
> Sure, but it is also a cleanly separable policy decision that we can make
after the more important half of the project happens :).  Lets do the more
important part first, then come back to this.
I'll buy that. ;-)
>> 2. (more important than #1) I'd like to understand the reason
behind
>> your preference for UpperCase names for ivars.  Is it just a personal
>> preference or is there a more profound reason?  So far, I've heard
>> that some people like lowerCase ivars (clear distinction from types,
>> etc), and some people don't think that helps much.  However,
I'm yet
>> to hear why UpperCase ivars are considered *better* than lowerCase, so
>> I'm curious.
>
> The only reason I suggested UpperCase for ivars is that *by far* the most
ivars are named like that in the current codebase.  If you're reading into
case for distinctions, one way to look at it is that lowerCase is for methods,
everything else is types or data.  I also think that public ivar names are much
less important than the other cases, particularly given how few there are.
All right.  That sounds reasonable.  Thanks for clarifying.

-- 
Zhanyong

Hi Chris,

I've uploaded a new patch to http://codereview.appspot.com/3264041.
It's also attached to this message.

I think I've addressed all your comments, except "when in doubt, an
enum should be a 'Kind'".  I don't think I fully understand
that
point, and it strikes me as a bit ad hoc for the coding standards.  Do
we really want it?

If you feel that's important, I'll add it -- but it will need some
clarification, as the Kind suffix clearly doesn't fit all enums.  What
is it that you really have in mind?

Thanks,

On Tue, Nov 30, 2010 at 5:18 PM, Zhanyong Wan (λx.x x) <wan at google.com>
wrote:
> On Tue, Nov 30, 2010 at 5:07 PM, Chris Lattner <clattner at
apple.com> wrote:
>>
>> On Nov 30, 2010, at 5:02 PM, Zhanyong Wan (λx.x x) wrote:
>>
>>> Thanks for the comments, Chris!  Glad that we are making progress.
>>>
>>> I'll make most of the edits you suggested later today.  Before
that,
>>> there are a couple of high-level points I'd like to go over
with you.
>>>
>>> 1. I totally agree that the biggest benefit of a naming convention
is
>>> uniform APIs.  On the other hand, an inconsistent local naming
style
>>> hurts the productivity of contributors and can lead to bugs by
causing
>>> confusion.  I'm fine with local variables having short names
when
>>> their scope is limited (say, fits within one screen) or their role
is
>>> obvious (like 'i' for an iterator), but I do find the
context
>>> switching annoying when I have to adjust for the different styles
as I
>>> move to different parts of the codebase.  Just something for you to
>>> consider.
>>
>> Sure, but it is also a cleanly separable policy decision that we can
make after the more important half of the project happens :).  Lets do the more
important part first, then come back to this.
>
> I'll buy that. ;-)
>
>>> 2. (more important than #1) I'd like to understand the reason
behind
>>> your preference for UpperCase names for ivars.  Is it just a
personal
>>> preference or is there a more profound reason?  So far, I've
heard
>>> that some people like lowerCase ivars (clear distinction from
types,
>>> etc), and some people don't think that helps much.  However,
I'm yet
>>> to hear why UpperCase ivars are considered *better* than lowerCase,
so
>>> I'm curious.
>>
>> The only reason I suggested UpperCase for ivars is that *by far* the
most ivars are named like that in the current codebase.  If you're reading
into case for distinctions, one way to look at it is that lowerCase is for
methods, everything else is types or data.  I also think that public ivar names
are much less important than the other cases, particularly given how few there
are.
>
> All right.  That sounds reasonable.  Thanks for clarifying.
>
> --
> Zhanyong
>


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

On Nov 30, 2010, at 11:29 PM, Zhanyong Wan (λx.x x) wrote:
> Hi Chris,
> 
> I've uploaded a new patch to http://codereview.appspot.com/3264041.
> It's also attached to this message.
> 
> I think I've addressed all your comments, except "when in doubt,
an
> enum should be a 'Kind'".  I don't think I fully
understand that
> point, and it strikes me as a bit ad hoc for the coding standards.  Do
> we really want it?
> 
> If you feel that's important, I'll add it -- but it will need some
> clarification, as the Kind suffix clearly doesn't fit all enums.  What
> is it that you really have in mind?
I think Chris means that if you're going to have a type that enumerates all
the different kinds of Blah, it should be called something like BlahKind.  Seems
like a good rule to me;  we have several competing conventions right now (e.g.
clang::CastKind, clang::Type::TypeClass, and llvm::GlobalValue::LinkageTypes),
and I do find myself having to look up these names a fair amount.

Enums for which "Kind" isn't an appropriate suffix shouldn't
be suffixed with "Kind".  I think there's a general principle
somewhere in there. :)

John.

On Nov 30, 2010, at 11:29 PM, Zhanyong Wan (λx.x x) wrote:
> Hi Chris,
> 
> I've uploaded a new patch to http://codereview.appspot.com/3264041.
> It's also attached to this message.
This patch looks great to me, please apply, thanks!
> I think I've addressed all your comments, except "when in doubt,
an
> enum should be a 'Kind'".  I don't think I fully
understand that
> point, and it strikes me as a bit ad hoc for the coding standards.  Do
> we really want it?
John's email sums it up really well, but I'm fine tackling this as a
separate step.

-Chris