Names
The first rule about naming again is some sort of a constitutional law for naming objects in a program - they should be simple, intuitive and consistent.
| Rule 12. Use a consistent and intuitive naming scheme. |
It is very important and helpful to use a consistent naming scheme. Functions and methods with similar behaviour should have similar names and contrary functions and methods with similar names should not behave different. This enables users to guess the correct name of a function or method and keeps them away from bad surprises. This in turn speeds up development cycles, reduces errors and frustration. For examples you should decide once if you prefer the prefix add or insert in conjunction with container classes, and then you should stick to it. Such small decisions greatly help to increase the usability of an API.
Especially in a big team, different developers tend to have different ideas about a canonical name for a specific function or method. In order to support consistent naming you should setup a special document describing common actions and their name. This document may include the following topics:
- Container methods. How should the method of container objects be called. add or insert? Or maybe even addObject or insertObject first or begin? remove or release?
| Rule 13. Use namespaces. |
You always should insert all your code into appropriate namespaces, this helps to prevent clashes with external libraries. It is even a good idea to separate different parts of your project into different sub-namespaces. It is a good practice to have one big namespace with the projects or the companies name that includes many other namespaces for different modules.
| Rule 14. The names of abstract data types, structures, typedefs, and enumerated types are to begin with an uppercase letter. |
The basic idea behind this rule is simple: All names of complex types like classes and structures should begin with a capital letter whereas instances of these objects should start with a lowercase letter. This helps reading the source-code by distinguishing between classes (which are some sort of meta-objects) and instances.
| Exception to 14. Typedefs for simple built-in data types (int's, floats's, etc.) may begin with a lowercase letter. |
The built-in types like int or float all begin with lowercase letters, so it would be quite unusual to force capital letters for simple typedefs. Consider the following examples:
typedef unsigned int uint32; typedef __int64 int64; typedef float real; |
| Rule 15. If a name consists of more than one word, the words are written together and each word that follows the first is begun with an uppercase letter. |
Examples
class Object { ... };
class ObjectContainer { ... };
enum ItemFlags { ... };
typedef Object Item;
typedef ObjectContainer ItemContainer;
|
Kaya Memisoglu 2005-01-06
