Naming
| Rule 22. Every global function begins with a verb and starts with a lowercase letter. |
As the name already states functions do something, so it is quite natural to chose verbs for their names. Of course a functions name may also contain a substantive or adjective, but it is considered good style that the first component of its name always is a verb. Have a look at the following examples:
// Good style File* openFile(const char* ); unsigned int getSize(const File* ); // Bad style void fileDelete(const char* ); // Call it deleteFile instead unsigned int fileSize(const File* ); // No verb! Call it getFileSize instead |
Of course this is a bad example in general, because normally you would create a class called File that contains appropriate methods, that is
class File {
public:
bool open(const char* );
unsigned int getSize() const;
...
};
|
| Rule 23. Overloaded functions may only differ in parameters but not in behaviour. |
This rule is a direct consequence of the rule of the thumb ''similar functions behave similarly''. It is a really bad thing if two functions with exactly the same name that only differ in their parameters behave differently. Such a clash will cause many bad surprises and is to be avoided under all circumstances.
| Rule 24. Avoid alias functions, that is two different names for the same logical function. |
In some cases you want to serve two different clients who have different ideas about canonical names. Under all circumstances you should avoid to create an alias method that is only a wrapper for another method with the sole purpose to offer two different names for one and the same function. This approach causes more confusion than comfort. Look at the following example
class Item;
class Container {
public:
void insert(Item* );
void add(Item* ); // Does the same
void addItem(Item* ); // Also does the same
};
|
In this example, both methods insert and add do exactly the same, probably one method is implemented simply by calling the other method. This is bad style and confuses people using your class.
One of the few exceptions to this rule includes the necessity to provide a deprecated method for compatibility reasons. In such cases, mark this method clearly as ''deprecated'' and give a link to the new method. But this on the other hand is a sign that your first API wasn't designed good enough, so there is no explicit exception for this rule.
Kaya Memisoglu 2005-01-06
