Still off topic, I know, but I was just re-reading the LLVM coding standards and I thought of this thread so I thought I would share this little section.
***
Name Types, Functions, Variables, and Enumerators ProperlyPoorly-chosen names can mislead the reader and cause bugs. We cannot stress enough how important it is to use descriptive names. Pick names that match the semantics and role of the underlying entities, within reason. Avoid abbreviations unless they are well known. After picking a good name, make sure to use consistent capitalization for the name, as inconsistency requires clients to either memorize the APIs or to look it up to find the exact spelling.
In general, names should be in camel case (e.g.
TextFileReader and
isLValue()). Different kinds of declarations have different rules:
Type names (including classes, structs, enums, typedefs, etc) should be nouns and start with an upper-case letter (e.g.
TextFileReader).
Variable names should be nouns (as they represent state). The name should be camel case, and start with an upper case letter (e.g.
Leader or
Boats).
Function names should be verb phrases (as they represent actions), and command-like function should be imperative. The name should be camel case, and start with a lower case letter (e.g.
openFile() or isFoo()).
Enum declarations (e.g. enum Foo {...}) are types, so they should follow the naming conventions for types. A common use for enums is as a discriminator for a union, or an indicator of a subclass. When an enum is used for something like this, it should have a Kind suffix (e.g.
ValueKind).
Enumerators (e.g. enum { Foo, Bar }) and public member variables should start with an upper-case letter, just like types. Unless the enumerators are defined in their own small namespace or inside a class, enumerators should have a prefix corresponding to the enum declaration name. For example,
enum ValueKind { ... }; may contain enumerators like
VK_Argument,
VK_BasicBlock, etc. Enumerators that are just convenience constants are exempt from the requirement for a prefix. For instance:
enum {
MaxSize = 42,
Density = 12
};
As an exception, classes that mimic STL classes can have member names in STL's style of lower-case words separated by underscores
(e.g. begin(), push_back(), and empty()).
Here are some examples of good and bad names:
class VehicleMaker {
...
Factory<Tire> F; // Bad -- abbreviation and non-descriptive.
Factory<Tire> Factory; // Better.
Factory<Tire> TireFactory; // Even better -- if VehicleMaker has more than one
// kind of factories.
};
Vehicle MakeVehicle(VehicleType Type) {
VehicleMaker M; // Might be OK if having a short life-span.
Tire tmp1 = M.makeTire(); // Bad -- 'tmp1' provides no information.
Light headlight = M.makeLight("head"); // Good -- descriptive.
...
}
