What makes a good routine name?
I. What is a good routine name?
A good routine name is a name that describes everything the routine does.
II. What makes a good routine name?
Here are guidelines for creating effective routine names:
- Describe everything the routine does:
In the routine’s name, describe all the outputs and side effects. Example
If you have routines with side effects, you will have many long, silly names like ComputeReportTotalsAndOpenOutputFile() routine above.
The solution is not to use less-descriptive routine names like ComputeReportTotals() routine name above, the solution is to program so that you cause things to happen directly rather than with side effects.
- Avoid meaningless, vague, or wishy-washy verbs:
Some verbs are elastic, stretched to cover just about any meaning. Example
These routine names above don’t tell you what it do. At the most, these names tell you that the routines have something to do with calculations, services, users, input and output.
Sometimes the only problem with a routine is that its name is wishy-washy (lacking in strength of character or purpose); the routine itself might actually be well designed.
Replace the wishy-washy routine name with good routine name, then you will have a pretty good idea of what the routine does.
In other cases, the verb is vague because the operations performed by the routine are vague. The routine suffers from a weakness of purpose, and the weak name is a symptom. If that’s the case, the best solution is to restructure the routine and any related routines so that they all have stronger purposes and stronger names that accurately describe them.
- Don’t differentiate routine names solely by number:
Sometimes, you will see something like this
One developer wrote all his code in one big function. Then he took every 15 lines and created functions named bigFunctionPart1(), bigFunctionPart2(),… After that he created one high-level function (bigFunction()) that called each part.
This method of creating and naming routines is especially egregious. But programmers sometimes use numbers to differentiate routines with names like the example above. The numerals at the ends of those names provide no indication of the different abstractions the routines represent, and the routines are thus poorly named.
- Make names of routines as long as necessary:
Research shows that the optimum average length for a variable name is 9 to 15 characters. Routines tend to be more complicated than variables, and good names for them tend to be longer.
On the other hand, routine names are often attached to object names, which essentially provides part of the name for free.
Overall, the emphasis when creating a routine name should be to make the name as clear as possible, which means you should make its name as long or short as needed to make it understandable.
- To name a function, use a description of return value:
A function returns a value, and the function should be named for the value it returns. Example
- To name a procedure, use a strong verb followed by an object:
A procedure with functional cohesion (you will read about routine cohesion in the later post) usually performs an operation on an object. The name should reflect what the procedure does, and an operation on an object implies a verb-plus-object name. Example
In object-oriented languages, you don’t need to include the name of the object in the procedure name because the object itself is included in the call. Example
- Use opposites precisely:
Using naming conventions for opposites helps consistency, which helps readablity. Example
- Establish conventions for common operations:
In some systems, it’s important to distinguish among different kinds of operations. A naming convention is often the easiest and most reliable way of indication these distinctions. Example
On this situation, we will need to establish conventions for ‘Get Id’ operations to avoid confusing.
Here is summary list of what makes a good routine name:
- Describe everything the routine does
- Avoid meaningless, vague, or wishy-washy verbs
- Don’t differentiate routine names solely by number
- Make names of routines as long as necessary
- To name a function, use a description of return value
- To name a procedure, use a strong verb followed by an object
- Use opposites precisely
- Establish conventions for common operations
Reference: Code Complete 2