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

Chris Lattner
Tue, 30 Nov 2010 18:56:21 -0000

On Nov 29, 2010, at 11:07 AM, Zhanyong Wan (λx.x x)
wrote:
> 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."

Completely agreed.

> Exceptions can be made (although rarely) when truly needed.

Wait, but the coding standards document also says not to use exceptions!
<sorry bad, joke> :)

> Csaba has pointed out the problem of possible clash (at least
> confusion) with macro names for variable names like MI.  I agree that

I don't think that conflict with macros should be worried about.  We've
had our own problems with macros (e.g. system headers that define things like
"i386") but there are straight-forward ways to deal with this. There
is no need to live life in fear :)

>> 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.

Yes, I see where you're coming from.  On the other hand, I don't see
that standardizing the names of local variables is particularly useful.  My
viewpoint of standardizing naming conventions is that it makes it obvious for
*clients of APIs* and prevents "having to look it up or think about
it" when you're interacting with various subsystems.  Local variables
inherently cannot be used by other subsystems.  If you're working on the
body of a function, it is reasonable (and not usually difficult) to figure out
what is going on in it.  In cases where it is difficult, the capitalization of a
variable isn't going to make it easier.

>From this perspective, I see that it is most important to standardize the
naming of: 1) types, 2) methods, 3) public instance variables, 4) enumerators.
If you agree, then we don't have to argue about/standardize "Type
type" or "MachineInstr *MI" vs "mi".  It also means far
less churn when someone decides to go crazy fixing the codebase. :)

Given that, here are some suggestions for a future rev of your patch:

+ In general, names of types, functions, and variables should be in
+camel case (e.g. TextFileReader and
isLValue ).

I'd suggest using isLValue() to make it clear that one
is a type and one is a function.

+Function names should be verb phrases

I completely agree, but it is worth adding a short justification, explaining
that methods are "actions".

+Variable (including function parameter) names should start with a lower-case
letter.

Please remove this.  In its place, we should have a naming rule for public
ivars, and for enumerations and enumerators.  I'd suggest ivars and enums
follow the same rules as types.  If there is a doubt, the enum should be a
"Kind", e.g. "ValueTy" in llvm/Value.h should be
"ValueKind".

Enumerators (unless they are in their own small namespace) should have a prefix.
For example, the enumerators in the ValueTy enum should be VK_Argument,
VK_BasicBlock, etc.  These rules shouldn't apply to enums that are just
convenience constants, like:

enum {
  MaxSize = 42,
  Density = 12
};

These should follow the same rules as ivars if they are members of classes.


Thank you for driving this forward Zhanyong, I think that this will make the
public APIs much more consistent and predictable!

-Chris