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

[Chris Lattner]

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:

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

I'd suggest using <tt>isLValue()</tt> 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