Naming Procedures

One of the most underrated concepts for top quality software engineering is naming procedures and variables.

A collection of software statements has one of several purposes:
Changing variables
Getting data from elsewhere
Sending data to elsewhere
In other words, making changes of one type or another. It is an activity and should be described with a verb or adverb phrase.
The code must do something to something. It must have an object of it's attentions. That object should be described with a noun phrase.
In the English language, verbs and nouns do not stand alone. The name of a function should consist of a verb or verb phrase and a noun or noun phrase. (The order is reversible. The reader should infer that words verb and noun may be replaced by verb phrase or noun phrase, but only a single and simple phrase for each.) The code must do something to something. The verb phrase should describe what the code does, and the noun phrase should describe what is being manipulated in the activity.

Every subroutine should be named using one verb or verb phrase and one noun or noun phrase. Conjunctive words such as and and or are not allowed. One and only one of each per name.
The name of the function should describe what the function does. It should describe everything the function does, and it should not describe or imply anything it does not do.
One of the first steps in developing good names is to stop trying to save effort in making short and abbreviated names. The time saved in not typing out a fully descriptive name is miniscule as compared to the time saved in reading the code and understanding right away what the function does. Further, a fully descriptive name provides several advantages.

Design: When you spend some time thinking of and creating a fully descriptive name, then you are spending time thinking about what the function will do and will not do. This period of thinking is really the most important part of software design. As Steven Covey said, "Begin with the end in mind." Spend some time thinking about that module before writing it, or even before writing its specification.

Validation and Verification: If the function is well named, then validating and verify the module is much easier.

Testing: Writing test procedures for well names modules is far easier that for poorly names modules.

Cohesion: A good name for a function may well be the first step in achieving a cohesive module. The importance of cohesion cannot be overstated. I will soon write a page on module cohesion. The topics are closely related, but merit separate treatment.

Some may argue that a single verb and noun may not be sufficient to adequately describe all modules. This is not the case. My recent work includes tracking antennas so I have derived a set of procedure names to describe a set of functions to drive an antenna system. For simplicity sake, we jump into the middle of the operation.

Example pseudo code
reposition_dish() // function to move the antenna to a new location
     {
     determine_desired_position(azimuth)
     determine_desired_position(elevation)
     calculate_position_error(azimuth)
     calculate_position_error(elevation)
     determine_servo_mode_type()
     set_axis_movement_rate( azimuth )
     set_axis_movement_rate( elevation )
     }

These examples may be a bit simplisitic, but they make the point. If you cannot think of a name with a single verb and a single noun that fully describes the purpose of the code, then the module is not well defined. Rethink the purpose of the module, refactor it, and rename it. Repeat until the module is well named.

Readers are encouraged email in some example and other comments for possible inclusion in these pages. Hopefully I will soon work on an email form, but until then, please send to:
webmail at bkelly dot ws.

December 2007