Make Names Fit
Chapter 1
Selecting names
A name is the result of a long deep thought process about the ecology it lives in. Only a
programmer who understands the system as a whole can create a name that "fits" with the system.
If the name is appropriate everything fits together naturally, relationships are clear, meaning is
derivable, and reasoning from common human expectations works as expected.
If you find all your names could be Thing and DoIt then you should probably revisit your design.
1. Class Names
− Name the class after what it is. If you can’t think of what it is that is a clue you have not
thought through the design well enough.
− Compound names of over three words are a clue your design may be confusing various
entities in your system. Revisit your design.
− Avoid the temptation of bringing the name of the class a class derives from into the derived
class’s name. A class should stand on its own. It doesn’t matter what it derives from.
− Suffixes are sometimes helpful. For example, if your system uses agents then naming
something DownloadAgent conveys real information.
2. Method and Function Names
Usually every method and function performs an action, so the name should make clear what it
does : checkForErrors() instead of errorCheck(), dumpDataToFile() instead of
dataFile(). This will also make functions and data objects more distinguishable. Classes are
often nouns. By making function names verbs and following other naming conventions programs
can be read more naturally.
Suffixes are sometimes useful :
− Max −to mean the maximum value something can have.
− Cnt −the current count of a running count variable.
− Key −key value.
For example : retryMax to mean the maximum number of retries, retryCnt to mean the current
retry count.
Prefixes are sometimes useful :
− is − to ask a question about something. Whenever someone sees Is they will know it’s a
question.
− get −get a value.
− set −set a value.
For example : isHitRetryLimit.
3. Variable Names
Make every variable name descriptive, limit the use of abbreviations or letter−words. It’s worth
writing words completely since it makes the code much more readable. Beware however that when
trying to find a good name, you don’t end up with with something like
’the_variable_for_the_loop’, use a proper English word for it like ’counter’ or ’iterator’.
English is a rich language and trying to find a correctly fitting word is important for code brevety,
cleanness and variation. Whenever in doubt, just use a thesaurus like Merriam−Webster
(http://www.m−w.com) or a rhyming dictionary like Rhyme
(http://rhyme.sourceforge.net/).
3.1. Exceptions
Some standard variables are used for often recurring tasks. Below is a list of those that are
accepted :
− i : integer counter
− it : STL−likeiterator
−
− tmp_
for the storage of temporary intermediate values
4. No All Upper Case Abbreviations
When confronted with a situation where you could use an all upper case abbreviation instead use
an initial upper case letter followed by all lower case letters. No matter what.
4.1. Justification
People seem to have very different intuitions when making names containing abbreviations. It’s
best to settle on one strategy so the names are absolutely predictable.
Take for example NetworkABCKey. Notice how the C from ABC and K from key are confused.
Some people don’t mind this and others just hate it so you’ll find different policies in different code
so you never know what to call something.
Chapter 2
Naming scheme
A standard naming scheme is important to ensure that all code looks similar and that every
developer can understand new code immediately without have to grasp a new naming scheme
first.
One of the main aspects of this naming scheme is that all names should contain key information
about the type of language construct is refers to. Additionally, certain prefixes will be used to
prevent common error in the use of basic C++ concepts such as pointers, references and scope.
This however doesn’t involve into a full−blownand difficult to understand and maintain Hongarian
notation.
1. Class Names
− Use upper case letters as word separators, lower case for the rest of a word
− First character in a name is upper case
− No underbars (’_’)
1.1. Justification
− Standard naming scheme in very clean OO languages such as Java.
− Stands out the best amongst the other names formatting, since a class is the basic element in
C++ this is a great benefit.
Example 2.1: Class Names Example
class NameOneTwo
class Name
2. Method Names
− Use upper case letters as word separators, lower case for the rest of a word
− First character in a name is lower case
− No underbars (’_’)
2.1. Justification
− Differentiates the first word part, which is often a verb. This makes it very clear what a method
does.
− Not exactly similar to class names and thus makes Class.doSomething() much more
readable as Class.DoSomething(), cleanly indicating through case which is which.
Example 2.2: Method Names Example
class NameOneTwo
{
public:
int doIt();
void handleError();
}
3. Class Member Names
− Member names should be prepended with the character ’m’.
− Member the ’m’ use the same rules as for class names.
− ’m’ always precedes other name modifiers like ’p’ for pointer.
3.1. Justification
− Prepending ’m’ prevents any conflict with method names. Often your methods and attribute
names will be similar, especially for accessors.
Example 2.3: Class Member Names Example
class NameOneTwo
{
public:
int varAbc();
int errorNumber();
private:
int mVarAbc;
int mErrorNumber;
String *mpName;
}
4. Method Argument Names
− The first character should be lower case.
− All word beginnings after the first letter should be upper case as with class names.
4.1. Justification
− You can always tell which variables are passed in variables.
− You can use names similar to class names without conflicting with class names.
Example 2.4: Method Argument Names Example
class NameOneTwo
{
public:
int startYourEngines(Engine &rSomeEngine, bool autoRestart);
}
ไม่มีความคิดเห็น:
แสดงความคิดเห็น