7.3. Good Routine Names

A good name for a routine clearly describes everything the routine does. Here are guidelines for creating effective routine names:

Cross-Reference

For details on naming variables, see Chapter 11, "The Power of Variable Names."

Describe everything the routine does In the routine's name, describe all the outputs and side effects. If a routine computes report totals and opens an output file, ComputeReportTotals() is not an adequate name for the routine. ComputeReportTotalsAndOpen-OutputFile() is an adequate name but is too long and silly. If you have routines with side effects, you'll have many long, silly names. The cure is not to use less-descriptive routine names; the cure 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. Routine names like HandleCalculation(), PerformServices(), OutputUser(), ProcessInput(), and DealWithOutput() don't tell you what the routines do. At the most, these names tell you that the routines have something to do with calculations, services, users, input, and output. The exception would be when the verb "handle" was used in the specific technical sense of handling an event.

Sometimes the only problem with a routine is that its name is wishy-washy; the routine itself might actually be well designed. If HandleOutput() is replaced with FormatAndPrintOutput(), you 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 One developer wrote all his code in one big function. Then he took every 15 lines and created functions named Part1, Part2, and so on. After that, he created one high-level function that called each part. This method of creating and naming routines is especially egregious (and rare, I hope). But programmers sometimes use numbers to differentiate routines with names like OutputUser, OutputUser1, and OutputUser2. The numerals at the ends of these 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 the return value A function returns a value, and the function should be named for the value it returns. For example, cos(), customerId.Next(), printer.IsReady(), and pen.CurrentColor() are all good function names that indicate precisely what the functions return.

Cross-Reference

For the distinction between procedures and functions, see Section 7.6, "Special Considerations in the Use of Functions," later in this chapter.

To name a procedure, use a strong verb followed by an object A procedure with functional cohesion 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. PrintDocument(), CalcMonthlyRevenues(), CheckOrderlnfo(), and RepaginateDocument() are samples of good procedure names.

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. You invoke routines with statements like document.Print(), orderInfo.Check(), and monthlyRevenues.Calc(). Names like document.PrintDocument() are redundant and can become inaccurate when they're carried through to derived classes. If Check is a class derived from Document, check.Print() seems clearly to be printing a check, whereas check.PrintDocument() sounds like it might be printing a checkbook register or monthly statement, but it doesn't sound like it's printing a check.

Use opposites precisely Using naming conventions for opposites helps consistency, which helps readability. Opposite-pairs like first/last are commonly understood. Opposite-pairs like FileOpen() and _lclose() are not symmetrical and are confusing. Here are some common opposites:

Cross-Reference

For a similar list of opposites in variable names, see "Common Opposites in Variable Names" in Section 11.1.

add/remove	increment/decrement	open/close
begin/end	insert/delete	show/hide
create/destroy	lock/unlock	source/target
first/last	min/max	start/stop
get/put	next/previous	up/down
get/set	old/new

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 indicating these distinctions.

The code on one of my projects assigned each object a unique identifier. We neglected to establish a convention for naming the routines that would return the object identifier, so we had routine names like these:

 employee.id.Get() dependent.GetId() supervisor() candidate.id()

The Employee class exposed its id object, which in turn exposed its Get() routine. The Dependent class exposed a GetId() routine. The Supervisor class made the id its default return value. The Candidate class made use of the fact that the id object's default return value was the id, and exposed the id object. By the middle of the project, no one could remember which of these routines was supposed to be used on which object, but by that time too much code had been written to go back and make everything consistent. Consequently, every person on the team had to devote an unnecessary amount of gray matter to remembering the inconsequential detail of which syntax was used on which class to retrieve the id. A naming convention for retrieving ids would have eliminated this annoyance.