Poorly-chosen names mislead the reader and cause bugs. We cannot +
Poorly-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.
+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 of types, functions, variables, and enumerators -should be in camel case (e.g. TextFileReader -and isLValue()). Type names (including classes, structs, -enums, typedefs, etc) should be nouns and start with an upper-case -letter (e.g. TextFileReader). An enum for all the -different kinds of something should be named with the Kind -suffix. Function names should be verb phrases (as they represent -actions) and start with a lower-case letter (e.g. a predicate may be -named isFoo() or hasBar(), while the name of a -command-like function should be imperative, -like openFile()).
+In general, names should be in camel case (e.g. TextFileReader +and isLValue()). Different kinds of declarations have different rules: +
-Enumerators 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, they should -have a prefix. 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 {
@@ -849,6 +863,10 @@ enum {
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()).
@@ -858,16 +876,16 @@ in STL's style of lower-case words separated by underscores
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
+ 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.
+ 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.
...
}