Some Rules For Good Naming

This Grumpy Programmer mailing-list essay got me thinking:

There is one point of contention I have with Laravel — some of the naming conventions that have causes numerous Twitter flame wars and blog posts. I speak, of course, about facades. … [T]he facade thing is a warning to remain vigilant and do your research into what everyone else calls something. Common vocabulary is critical when it comes time to solve difficult problems.

I completely agree with the emphasis on using a common vocabulary. One issue here is that naming things properly is very, very hard. It is one of the only two hard problems in programming.

Are there any rules (even rules-of-thumb) that can we use to make it easier to pick good names for the classes and concepts in our projects?

What’s In A Name?

Above all, a good name makes it obvious what we are describing. It provides clarity by itself without the need for further explanation.

However, because a word can be ambiguous, we have to pick the proper context for the use of a name. Using the right context when picking a name is paramount.

Unfortunately, in programming, there may be overlapping contexts. Giving a name to a domain class or concept can be especially difficult because of this overlap. Do we name an element for what the domain experts call it in their normal day-to-day work, or for its layer in the overall system, or for the pattern of its design?

Not A Novel Context

The first thing we have to remember, then, is that we are not writing a novel in English. Instead, we are writing software instructions. We are writing these instructions in something other than a normal human language. We are writing these instructions for a computer, and simultaneously writing them for human readers of that programming language.

With that in mind, I suggest the following order of priority for picking the proper context for a name:

1. 
   

   First is the vocabulary, common idioms, and core resources of the programming language itself. If the language itself, its core classes and methods, or the common expressions of its professional programmers associate particular vocabulary words with a concept, activity, or behavior, we should choose from among those words first when attempting to pick a name.

   
   


2. 
   

   Second is the vocabulary and common idioms related to previously identified patterns of software design. If there is a software design pattern that matches the concept we are trying to express, its name should be our next-best choice.

   
   


3. 
   

   Third is the vocabulary, idioms, jargon, and slang related to the domain. If there is no appropriate word from the programming language, and no relevant software design pattern, then falling back to the domain for the naming context is our next priority.

   
   


4. 
   

   The absolute last context should be words from normal everyday interactions. We use these words only after exhausting the other three contextual options. This is the least-appropriate context for picking a name.

   
   

This priority order is probably the opposite of what many would prefer. As human beings, we are more fluent and familiar with the vocabulary of our everyday writing and speech. It took many years of hard work to acquire that vocabulary in the first place, and we are unwilling to do additional hard work to acquire yet another vocabulary that applies more appropriately the context of programming. We would prefer to reuse the words we already know, instead of learning how to apply new words.

Even so, to be good at communicating the concepts of software programming to other programmers, it is incumbent upon us as professionals to expand our vocabulary. We must learn these new terms and their proper use. This is especially difficult with patterns of software development.

When it comes to patterns, we have to remember that the patterns themselves pre-exist their names. The names were applied only after seeing the same patterns over and over again in many different programs. This means that it is the behavior of a construct that determines what its appropriate pattern-related name should be. If we write code like this …

<?php
class Foo
{
    public function newInstance($bar)
    {
        return new $bar;
    }
}
?>

… and we never mention the word “factory”, the code is still representative of the Factory pattern. A rose by any other name may smell as sweet, but if we call it a daisy then nobody will be able to guess that it has thorns. Similarly, a

Truncated by Planet PHP, read more at the original (another 3392 bytes)

more