[llvm-commits] [llvm] r137497 - /llvm/trunk/docs/CodingStandards.html

John McCall rjmccall at apple.com
Fri Aug 12 14:31:36 PDT 2011


On Aug 12, 2011, at 1:29 PM, Chris Lattner wrote:

> 
> On Aug 12, 2011, at 1:19 PM, John McCall wrote:
> 
>> On Aug 12, 2011, at 12:49 PM, Chris Lattner wrote:
>>> URL: http://llvm.org/viewvc/llvm-project?rev=137497&view=rev
>>> Log:
>>> apparently variable naming conventions never got added, document the
>>> prevailing convention.
>> 
>> Aww.  I was doing my bit to change the prevailing convention.
>> 
>> I know this is a bikeshed topic, but I actually dislike this convention
>> quite a bit.  There's value in being able to tell, at a glance, what kind
>> of declaration an identifier refers to.   Functions are already
>> distinguished because (in all but vanishingly uncommon cases)
>> they're immediately followed by a left-paren.  Namespaces are
>> distinguished because they're always followed by :: (and they're
>> not capitalized, and so aren't confusable with types — a good
>> example of good capitalization rules clarifying the code!).  Enums
>> are distinguished because of the prefix mangling.   But the
>> "capitalize everything else" convention makes it impossible
>> to distinguish between different kinds of variables and fields, and
>> those are frequently used in analogous situations and are very
>> useful to distinguish.
> 
> I can see where you're going on this, but there are several specific concerns I have:
> 
> 1) this interferes with contractions like the much lauded "LI".  Using "li" doesn't read right and is harder to parse.

I do agree that abbreviations are an interesting case that would merit
an exception.

> 2) If it's hard to tell whether a variable is local or not, it is named poorly.  Variable names should be descriptive if they have a large scope, and short if they don't.  If it is hard to tell whether something is a local variable, something else is going wrong.

This is basically unfalsifiable — past experience shows that it's
essentially impossible to show one programmer some existing
variable names and not have them come up with some criticism.

Anyway, your "length of scope" rule is basically bunk.  Most people
would consider using descriptive names for variables to be a good
thing, even if the variable only lives for five lines and three of them
are comments.  Descriptive names do not tell you where something
is stored unless you are already intimately familiar with the code.
Yes, humans have an amazing capacity for language which lets them
learn and internalize enormously complicated sets of context-specific
rules, idioms, and exceptions.  People who are already intimately
familiar with the code are not the primary beneficiaries of naming
conventions — it's the people who are intimately familiar with the
code "next door".

John.



More information about the llvm-commits mailing list