Some Rules For Good Naming

By | April 29, 2014

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.

Patterns Are Defined By Behavior

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 “factory” by any other name still creates and returns objects. Calling the above construct anything other than “factory” (or a factory-related name) removes clarity instead of providing it.

Picking The Closest Pattern

As a related issue, it’s not enough to look through pattern definitions and find one that is “close enough.” We must find the best one we can that matches the most parts of the concept we are trying to express in a name. This can be a lot of effort.

By analogy, we should not call a “motorcycle” a “bicycle” and expect to be understood fully. Yes, a “motorcycle” matches up with a “bicycle” in important ways: they both have two wheels, we steer and brake with our hands instead of our feet, we sit on a seat above the frame, and so on.

But for all their similarities, they are clearly different things. Better to call a motorcycle by its proper name so that we impart better understanding. Likewise, better to call something a Proxy instead of a Facade when appropriate.

Avoid Claiming A Special Context

When picking a context for a name, it is very tempting to define our own special context that lets us pick a name we prefer, perhaps for marketing or other non-technical reasons. We need to avoid this temptation.

Imagine if General Motors, in its marketing materials, called a “Kia” a “Maserati” and went on to describe its offerings in terms of its so-called Maserati. Such a description would make no sense in the wider world of automobile manufacture. Calling a “Kia” a “Maserati” while “in the context of GM” is symptomatic of the Humpty-Dumpty rationale:

“When I use a word,” Humpty Dumpty said, in a rather scornful tone, “it means just what I choose it to mean — neither more nor less.” “The question is,” said Alice, “whether you can make words mean so many different things.” “The question is,” said Humpty Dumpty, “which is to be master — that’s all.”

Claiming your own special context adds a layer of unnecessary obfuscation and cognitive friction. It removes clarity in naming.

Summary

In summary, I opine that these are the guidelines we need to keep in mind when picking names:

  • We are writing software instructions, not prose or poetry.

  • Pick from existing names that provide clarity within the appropriate context.

  • The order of priority for the appropriate context is: programming language, software patterns, domain terms, and finally everyday speech.

  • When using a pattern name, find the best match, not one that is merely close-enough.

  • Avoid claiming a special context for names so that you can make them mean what you want, instead of what they mean within a more widely shared context.


UPDATE: Some commenters from the Laravel community are being, shall we say, uncivil in their statements. Comments that are not civil, polite, respectful, and on-topic will be deleted out of hand. I reserve the right to further police comments as I see fit.

14 thoughts on “Some Rules For Good Naming

  1. Seth Thornberry

    I would like to see some examples of this being applied in a concrete system. The rules seem like they may make sense when you’re writing a framework or abstract library since your domain is programming, but I fail to see how this applies to logic that models business processes. I would prefer that my naming convention allowed me to communicate about the logic without naming core business objects over implementation details. If I am using a set of line items with meta data I would rather call it an Invoice than a LineItemCollection.

    Reply
  2. Hari KT

    Hey Paul,

    Thank you for the list. But when trying to name we should be familiar with these patterns in-order to say I am going to use X pattern. I feel it is for the easiness and not to spend too much time reading those people name it wrongly ( include me also :) ) .

    By the way there is a typo in the sentence. matches matches.

    > We must find the best one we can that matches matches the most parts of the concept we are trying to express in a name

    Thank you

    Reply
  3. Auke van Slooten

    Thank you for carefully working out something most of us only rarely really think about.
    I have only one comment: I think naming something based on the jargon of the domain may often be preferable to the software design pattern name. One of the core tasks of a developer is to learn new problem domains and understand them well enough to create software for them. So in some contexts the domain specific names will make more sense than more generic software pattern names. You could create a mix of the two I suppose, but that could result in long unwieldy names.

    Reply
  4. gggeek

    I also tend to agree with the POV of aligning names with the concepts coming down from the business-requirements.
    At least for classes which represent business-logic entities.
    And if they implement any interface or pattern, let be it.

    The problem with using names which adhere too closely to the implementation is that a) if you move your factory to a singleton, you should change the name as well, and b) different developers pick different patterns, cs books and implementation styles, so in a project with many people onboard its easy to end up with a mess on your hand.

    It is true that business requirements do change, and you might ask yourself: shall I rename my code entities when the requirements change? Well, yes. Even if it is perceived as as cost, this actually makes sense, if you consider that your classes will be evolving their functionality (since they are not the same anymore, they get a new name). It also makes life easier down the line for the next-code-maintainer

    Reply
  5. Pingback: Paul Jones: Some Rules For Good Naming | facebooklikes

  6. James Fuller

    I am inclined to believe that good naming is much like good art; you can’t define it, but you know it when you see it!

    My team generally tries to name classes or methods after the things they do, e.g. OrderCreator or UserRetriever. However naming after a pattern is sometimes more appropriate when you have to name something by what it IS, e.g UserDeletionStrategy, ArticleFactory. Sometimes the interface itself carries the burden of the pattern name like SplObserver or SplSubject.

    Having said that, allow me to throw in a method naming gripe:
    I can’t stand overly generic / common method names such as get(), post(), query(), request(). They may lead to pretty api’s but make searching and refactoring difficult in many situations. (legacy code situations that is)

    Reply
  7. Greg

    > Some commenters from the Laravel community are being, shall we say, uncivil in their statements.

    I can’t imagine why they would be. Your position is essentially “I’m right and you’re wrong”, even though you know as well as anyone that language doesn’t work that way. Yes, there are some conventions which go with the term “Facade Pattern”, but this does not mean that everything that is called a Facade must comply with it.

    Your continued crusade against a small detail (an incredibly small detail…) makes you look, well, petty. Statements in other media where you claim that somehow it will fall to “You” to re-educate people is outright disrespectful because it is predicated on the belief that you are somehow superior in your knowledge and other people can’t think or work things out for themselves.

    Perhaps certain elements of the Laravel community are being unkind because they are sick to their back teeth of this utter non-argument. They are called Facades in Laravel. It is a legitimate use of the word. Laravel makes no suggestion or implication (and as far as I can tell, never has) that they conform with the Facade Pattern – and simple use of the word Facade does not in any way constitute such a suggestion.

    I think it’s time to withdraw from this pointless crusade. You are thoroughly in the wrong – and aside from your own little echo chamber literally nobody else in the community gives a shit about it.

    Reply
    1. pmjones Post author

      > Your position is essentially “I’m right and you’re wrong”, even though you know as well as anyone that language doesn’t work that way.

      My position is essentially that “Laravel misuses the word Facade” even though you know as well as anyone that arguments against that position are post-hoc rationalizations.

      > Your continued crusade against a small detail (an incredibly small detail…) makes you look, well, petty.

      Your continued refusal to correct a small detail (an incredibly small detail…) makes you look, well, petty.

      > Laravel makes no suggestion or implication (and as far as I can tell, never has) that they conform with the Facade Pattern – and simple use of the word Facade does not in any way constitute such a suggestion.

      The code in question *does in fact* conform with the Proxy pattern, and should be called as such. Calling it a Facade is a misuse of the term Facade. Note the sections “Patterns Are Defined By Behavior” and “Picking The Closest Pattern” above.

      > I think it’s time to withdraw from this pointless crusade. You are thoroughly in the wrong – and aside from your own little echo chamber literally nobody else in the community gives a shit about it.

      I think it’s time to withdraw from the pointless refusal to correct your mistake. You are thoroughly in the wrong – and aside from your own Laravel echo chamber almost nobody else agrees with you.

      Also, you are literally wrong that literally nobody else in the community cares. There is a non-zero number of people besides myself who think this is at least somewhat important. For someone who talks about “how language works” I find your error amusing.

      Reply
      1. Greg

        For starters, it isn’t my mistake to correct. The decision to a) acknowledge it is a mistake and b) ultimately decide to correct it is Taylor’s. Not mine, and not yours. There is a completely rational argument that it is not a mistake in the first place.

        Just because you right a blog post where you define an opinion that you hold to be true for rules of naming does not mean that anyone else needs to hold those rules to be true at all. For example, I always hold that the names of things should represent the domain first and foremost. If in my domain “factory” or “builder” or “adapter” have specific meaning my position would be that it is more important to look to the domain than to the GoF. Opinions are like assholes – we’ve all got them.

        I will withdraw my hyperbole about literally nobody in the community giving a shit. It would seem to be correct at least that nobody else in the community is launching into a debate at every opportunity over the semantics of one element of that framework.

        Reply
        1. pmjones Post author

          > There is a completely rational argument that it is not a mistake in the first place.

          There is a post-hoc rationalization, yes. But that rationalization is to cover the fact of the mistake.

          > For example, I always hold that the names of things should represent the domain first and foremost.

          Even under that rule, Laravel “facades” are misnamed. The Laravel domain is that of a general-purpose web framework, thus placing it within the context of software patterns, and not in the context of common English.

          > I will withdraw my hyperbole about literally nobody in the community giving a shit.

          Accepted.

          > It would seem to be correct at least that nobody else in the community is launching into a debate at every opportunity over the semantics of one element of that framework.

          Yes, I have come to consider it my burden to bear. I wish more people had higher attention to detail in this case.

          Reply
          1. Greg

            > Even under that rule, Laravel “facades” are misnamed. The Laravel domain is that of a general-purpose web framework, thus placing it within the context of software patterns, and not in the context of common English.

            No doubt – but those are “my” rules. Taylor may hold other rules to be true – I wouldn’t know, you’d have to ask him. My point is that it is all entirely based on opinion. You can arrange any of your 4 rules in any order that you can rationalize. “Naming is hard”, etc.

            > Yes, I have come to consider it my burden to bear. I wish more people had higher attention to detail in this case.

            This is what genuinely confuses me though. Why is it your burden to bear? I can come up with several theories but the nearest I’ve seen to you making a case for why you keep flogging this particular dead horse is that you believe that it is going to somehow damage developers and that it would be your duty to “retrain” those developers.

          2. pmjones Post author

            > Taylor may hold other rules to be true

            He might, but he knows the name is wrong. Note that all the rationalizations are coming from Laravel followers, not from him.

          3. Greg

            > Note that all the rationalizations are coming from Laravel followers, not from him.

            I believe he has personally put forward the “dictionary meaning” rationalization, and at least implied that was his original intent from the get go. Hard to actually know his intentions from tweet-length statements.

          4. pmjones Post author

            “Dictionary meaning” in a software context is, as I and others have noted, the wrong approach. In software, one should be using software terms that provide clarity. Otherwise he *has* no rules for picking names and does “whatever.” Add to that, he recognizes that he probably should have chosen otherwise, as he reveals here: http://www.reddit.com/r/PHP/comments/1v2s1b/response_stop_using_facades/ceoh8o8

            I repeat again: *everyone else* making post-hoc justifications for him, and his own post-hoc justifications, are misguided attempts to cover for a naming mistake.

Leave a Reply

Your email address will not be published. Required fields are marked *