Naming things

    There are only two hard things in Computer Science: cache invalidation
    and naming things.

    — Phil Karlton

    We, developers, spend more time reading code than writing it. It is important for the code to be readable and clear about its intent.


    Below are some advice based on my experience naming things.


    Meaning


    A name, be it a variable, a property, a class, or an interface, should reflect the purpose of why it's being introduced and how it's used.


    Use accurate names


    If one can not get an idea about usage and purpose without extra comments the name is not good enough. If immediate usage or purpose idea based on naming is wrong then the naming is unacceptable.


    The worst possible naming is when a method name lies to the one who reads it.


    Avoid meaningless names


    These are names like $i, $j, $k etc. While these are OK to use in cycles, in other cases they are wasting readability.


    A common source of such names is classic science where most formulas use one-letter variables so it is faster to write. As a consequence, you can not make sense of these formulas without an introductory paragraph explaining naming. Often this paragraph is hard to find.


    Since computer science education includes significant number of classic science disciplines, students are getting used to such naming and bring it to programming.


    Naming classes, interfaces, properties and methods


    Class name should be one or several nouns. There should be no verbs. Try avoiding "data", "manager", "info", "processor", "handler", "maker", "util" etc. as these usually an indicator of vague naming.


    Interfaces are usually either nouns or adjectives. Some teams, including PHP-FIG, chose to postfix interfaces with Interface. Some do it with I prefix and some use no prefix or postfix. I find all these acceptable in case you are consistent.


    Properties should be named with nouns or adjectives. For booleans use affirmative phrases prefixing with "Is", "Can", or "Has" where appropriate.


    Method names should contain one or more verbs as they are actions. Choose verb that describes what the method does, not how it does it.


    While it is not strictly necessary, it is a good idea to end derived class name with the name of the base class:


    class Exception {}
    
    class InvalidArgumentException extends Exception {}

    Consistency


    Use a single name for a single concept. Be consistent.


    A good example is using begin/end everywhere instead of mixing it with start/finish.


    Follow code style conventions


    When developing a project, a team must agree on code style and naming conventions they use and follow these. If a part of conventions is not accepted by some team members then it should be reviewed, changed and new rule should be set.


    For PHP the most common convention is currently PSR-2 and most internal project conventions are based on it.


    Verbosity


    Avoid reusing names


    Using same name for many concepts should be avoided if possible as it brings two problems:


    • When reading, you have to keep context in mind. Usually that means getting to namespace or package declaration constantly.
    • Searching for such names is a pain.

    Avoid contractions


    Do not use contractions. Common examples are:


    • cnt
    • iter
    • amnt
    • impl

    function cntBigWrds($data, $length)
    {
        $i = 0;
        foreach ($data as $iter) {
            if (mb_strlen($iter) > $length) {
                $i++;
            }
        }
        return $i;
    }
    
    $data = ['I', 'am', 'word'];
    echo cntBigWrds($data, 3);

    The code above when named properly becomes:


    function countWordsLongerThan(array $words, int $minimumLength)
    {
        $count = 0;
        foreach ($words as $word) {
            if (mb_strlen($word) > $minimumLength) {
                $count++;
            }
        }
        return $count;
    }
    
    $words = ['I', 'am', 'word'];
    echo countWordsLongerThan($words, 3);

    Note still that short explanatory names without contractions are better than long explanatory names so do not take verbosity to extreme ending up with names like processTextReplacingMoreThanASingleSpaceWithASingleSpace().


    If the name is too long it either means it could be re-worded to make it shorter or the thing you are naming is doing too much and should be refactored into multiple things.


    Avoid acronyms


    Avoid acronyms and abbreviations except commonly known ones such as HTML. Elon Musk sent an email titled "Acronyms Seriously Suck" to all SpaceX employees in May 2010:


    There is a creeping tendency to use made up acronyms at SpaceX. Excessive use of made up acronyms is a significant impediment to communication and keeping communication good as we grow is incredibly important. Individually, a few acronyms here and there may not seem so bad, but if a thousand people are making these up, over time the result will be a huge glossary that we have to issue to new employees. No one can actually remember all these acronyms and people don't want to seem dumb in a meeting, so they just sit there in ignorance. This is particularly tough on new employees.

    That needs to stop immediately or I will take drastic action — I have given enough warning over the years. Unless an acronym is approved by me, it should not enter the SpaceX glossary. If there is an existing acronym that cannot reasonably be justified, it should be eliminated, as I have requested in the past.

    For example, there should be not "HTS" [horizontal test stand] or "VTS" [vertical test stand] designations for test stands. Those are particularly dumb, as they contain unnecessary words. A "stand" at our test site is obviously a test stand. VTS-3 is four syllables compared with "Tripod", which is two, so the bloody acronym version actually takes longer to say than the name!

    The key test for an acronym is to ask whether it helps or hurts communication. An acronym that most engineers outside of SpaceX already know, such as GUI, is fine to use. It is also ok to make up a few acronyms/contractions every now and again, assuming I have approved them, e.g. MVac and M9 instead of Merlin 1C-Vacuum or Merlin 1C-Sea Level, but those need to be kept to a minimum.

    I agree with him.


    Readability


    Code should be able to be read as easily as prose. Choose words that you would choose writing an article or a book. For example, a property named TotalAmount is more readable in English than AmountTotal.


    Hiding implementation details


    That is more about object oriented design but it affects readability much if implementation details are exposed. Try not to expose methods named like:


    • initialize
    • init
    • create
    • build

    Domain language


    Code should use the same names as used in the business or domain model automated.


    For example, if a travel business using "venue" as a general name for cafes, hotels and tourist attractions, it is a bad idea to use "place" in the code because you and your users will speak two different languages making it more complicated than it should.


    Such a language is often called "The Ubiquitous Language". You can learn more from "Domain Driven Design Quickly" mini-book by InfoQ.


    English


    Majority of programming languages use English for built-in constructs and it is a good practice to name things in English as well. It is extremely important for a developer to learn English at least on the basic level and, what is more important, to have good vocabulary that one can use for finding a good name.


    Some useful tools:



    References


    Support the author
    Share post

    Comments 5

      +5
      While the topic is very interesting and indeed important, this particular post barely has value. It just reiterates boring trivia that's been floating around forever, like «identifiers should have meaninful names», how long is this mantra repeated without really being helpful? To make a discussion of this topic interesting someone might want to throw in cognitive science, add stunning quotes from stars like Linus Torvalds, have proven real life examples when changing a naming policy saved a project, compare naming schemes from various projects including software and stuff like math papers. In it's current form this text is for kids starting to learn their first programming language, and I would probably not let them read it because it just imposes unproven dogmas, confuses and will limit their creative thinking without any good.

      Now the fun part, for starters just prove that

      thing->Energy = thing->Mass() * np.math.pow(lib.constants.speedOfLightInVacuum, 2)

      is a better practice than this:

      E = m * c^2

      If you avoid acronyms until they become well recognized, how they become well recognized?

      An advice to conceal properties named create and destroy is silly, this is a design advice not the naming advice, choosing whether to expose it or not has nothing to do with «naming» it, if it creates something, it will still be called «create».

        +1
        If you avoid acronyms until they become well recognized, how they become well recognized?

        Why should they be recognized in programming?


        E = mc2 is a bad example. It is a product of quite complicated math-backed work done by Albert Einstein with the help of Marcel Grossmann. The work took years of fiddling with equations and doing that is essentially focusing on the form ignoring the meaning. That's where single-letter variables are handy and that's what mathematics is about: it is refactoring of the form to make it simpler. Meaning doesn't matter until refactoring is done. In case of Einstein it took large part of his life so, I guess, he got used to the naming because he was writing these more than reading.


        In programming it is different. We introduce our own variables that usually are unique per domain we implement. Therefore, there is not much to reuse from other domains. Unlike math, we cannot work without understanding initial problem because while form matters, our job is to solve problems.

          +1
          Now the fun part, for starters just prove that

          thing->Energy = thing->Mass() * np.math.pow(lib.constants.speedOfLightInVacuum, 2)

          is a better practice than this:

          E = m * c^2

          I think, one-letter variable names are good when you write one-line programs, a.k.a formulas. Usually, formulas are accompanied with a sheet of text explaining meaning of all things inside the formula.

          So, if you want write something like this

          $E = $m * $c ** 2


          Then you need to write some documentation explaining meaning of $E, $m, and $c. But you don't need to write such documentation when you write something like this

          $energy = $mass * $lightSpeed ** 2


          thing->Energy = thing->Mass() * np.math.pow(lib.constants.speedOfLightInVacuum, 2)

          is a better practice than this:

          E = m * c^2

          Did you mean, that this is a better alternative?

          thing->E = thing->m() * np.math.pow(lib.constants.c, 2)

          I mean, you're comparing non-programming notation with an example of code. And the code example uses different language constructs which are specific to the language and which are not learned in school by everybody.
        • UFO just landed and posted this here
            0

            Indeed, such a long names are stupid but Box_2 isn't a good name as well. In case we're talking object-oriented paradigm, the variable in question is likely to belong to a class. Class context will clarify part of the variable context so that part could be subtracted from the variable name. Then, another part of the context could be namespace or package name. Likely, after taking the context into account, variable name won't be that long anymore.


            From my experience, naming takes time and names like Box_2 are used when developers do not care about naming or are in a big hurry.

          Only users with full accounts can post comments. Log in, please.