From 7fcd4dcb98d2e2bec231e713aefd2cacc879dd33 Mon Sep 17 00:00:00 2001 From: Zhanyong Wan Date: Thu, 2 Dec 2010 05:10:07 +0000 Subject: Add naming rules to the coding standards. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@120689 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/CodingStandards.html | 67 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) diff --git a/docs/CodingStandards.html b/docs/CodingStandards.html index a2420805ec..4af3c6a5bf 100644 --- a/docs/CodingStandards.html +++ b/docs/CodingStandards.html @@ -51,6 +51,7 @@
  • The Low-Level Issues
      +
    1. Name Types, Functions, Variables, and Enumerators Properly
    2. Assert Liberally
    3. Do not use 'using namespace std'
    4. Provide a virtual method anchor for @@ -807,6 +808,72 @@ locality.

      + +
      + Name Types, Functions, Variables, and Enumerators Properly +
      + +
      +

      Poorly-chosen names 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.

      + +

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

      + +

      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 {
+  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 bad and good 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.
+  ...
+}
+
      +
      + +
      + +
      Assert Liberally -- cgit v1.2.3