Introduce yet another C++ naming style

[Mine]

Hi All,

This email is to introduce a naming style I used in previous project, which
I think is elegant and makes the code more friendly to read.
I just want to share this style for discussion and if you think it’s
better, we may use this style in OpenBMC projects.

In recent reviews I see some comments about the problems and debate on C++
class’s members and function parameters.

E.g.

   1. In generated sdbusplus code, we may happen to use C++’s keywords as
   class members, such as server::Delete::delete. This is address by
   https://gerrit.openbmc-project.xyz/#/c/1481/
   2. Sometimes we use the same name for a class’s member and function
   parameter, such as:

   class Host {
     sdbusplus::bus::bus& bus;
     Host(sdbusplus::bus::bus& bus, ...)
      : bus(bus)
     {...}
   };

   This is OK, but some reviewers/readers may feel a bit strange on the
   code.
   Some one prefer underscores like _bus to resolve this issue, some other
   may feel bus is just good.
   3. We may want to define a object with the same name as class’s name,
   such as:

   class foo {
     ...
   };//foo foo; // This does not compile
   foo myFoo; // We'll have to use a different name

   4. During reading the code, sometimes it’s hard to find if a variable is
   a local varialbe, or the class’s member, or a constant, such as:

   class Host {
    std::string somePath;
   };
   ...const char* constPath = "xxx";
   Host::xxx(const char* anotherPath) {
    std::string theThirdPath;
    // In this function, how do we tell if xxxPath is a local variable
or class's member?
   }


The naming style I introduce will address all these “problems”.

   1. All classes, structs, enums start with “T”, e.g. TUpperCamelCase
   2. All interfaces (with pure virtual functions) starts with “I”, e.g.
   IUpperCamelCase
   3. All members and functions of a class use UpperCamelCase
   4. All function parameters and local variables uses lowerCamelCase
   5. All const or constexpr uses ALL_UPPER_CASE, the same for enum’s
   values.

*Note:* All these styles apply to application code, if the code is to
provide a library like STL, keep STL style.

With the above styles, we can see all the above “problems” are resolved:

   1. Because class members are in UpperCamelCase, so it will not use C++’s
   reserved keywords at all;
   2. Because classes are in TUpperCamelCase, and parameters are in
   lowerCamelCase, we won’t have same names for class members and function
   parameters

   class THost {
    sdbusplus::bus::bus& Bus;
    THost(sdbusplus::bus::bus& bus, ...)
     : Bus(bus)
    {...}
   };

   3. Because classes are in TUpperCamelCase, we can always define a
   variable/member with the name we like:

   class TFoo {
     ...
   };
   TFoo Foo; // OK for class member
   TFoo foo; // OK for local variables

   4. We can always tell if a variable is a class’s member, or a local
   variable, or constants, or a function call.

   class THost {
     std::string SomePath;
     enum class TValue {
       ONE,
       TWO,
       THREE
     };
   };
   ...const char* CONST_PATH = "xxx";
   THost::xxx(const char* anotherPath, TFoo* foo) {
     std::string theThirdPath;
     foo->InvokeMethod();
     // By reading the code (even with header file), we know:
     //
     // "SomePath" is class's member as THost::SomePath
     // "CONST_PATH" and "ONE/TWO/THREE" are constants
     // *anotherPath* and *theThirdPath* are local variables
     // "foo->InvokeMethod()" is to call TFoo::InvokeMethod() function
   }


I think this style is simple and effective, and it improves readability.
What do you think?

—
BRs,
Lei YU
​
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.ozlabs.org/pipermail/openbmc/attachments/20161220/8875cf57/attachment.html>