On names - Embedded.com

On names

The Linux printk function has a number of logging levels, which include KERN_EMERG, KERN_ERR and others.

What, exactly, does EMERG mean? Emergency? Emerging? Emergent? The latter sounds like part of the title of a horror movie.

Or ERR – perhaps that’s error, but it could be to err, or erroneous. Maybe even erogenous (nearly, and definitely my preference). Combine that with KERN (definition: “a part of the face of a type projecting beyond the body or shank”) and the puerile possibilities are positively provocative.

Why is every index variable named i, j or k? Or, for nested loops, ii. Or my personal favorite, iii? The reason is because 60 years ago, when Fortran came out, variables starting with the letters i through n were, by default, integers. Few remember this, but most of us still mindlessly practice it. I suspect few readers have ever even used Fortran.

It’s interesting that some believe long names yield self-documenting code (which isn’t true) yet so many of us abbreviate to the point of obfuscation. The code has to do two things: work, and express its intent to a future version of yourself or to some poor slob faced with maintaining it all years from now after you’re long gone. If it fails to do either, it’s junk. I’ve met plenty of developers who say they really don’t care what happens after they move on to another job or retire. But if we are professionals we must act professionally and do good work for the sake of doing good work.

Clarity is our goal. Names are a critical part of writing clear code. It’s a good idea to type a few additional characters when they are needed to remove any chance of confusion.

Pack the maximum amount of information you can into a name. I had the dreary duty of digging through some code last month where no variable name exceeded three characters. And there were a lot of variables! The mess was essentially unmaintainable, which seemed to be one of the author’s primary goals.

We’ve known how to name things for 250 years. Carl Linnaeus taught scientists to start with the general and work towards the specific. Kingdom, Phylum, Class, Order, Family, Genus, Species. Since in the West we read left-to-right, seeing the Kingdom first gets us in the general arena, and as our eyes scan rightward more specificity ensues. So read_timer is a really lousy name. Better: timer_read. timer_write. timer_initialize. A real system probably has multiple timers, so use timer0_read, timer0_write. Or even better, timer_tick_read, timer_tick_write. One could also make a good argument for tick_timer_read.

The Linnaean taxonomy has worked well for centuries, so why not use a proven approach?

Avoid weak and non-specific verbs like “handle,” “process” and “update.” I have no idea what “ADC_Handle() ” means. “ADC_filter() ” conveys much more information.

I do think that short toss-away names are sometimes fine. A tight for loop can benefit from a single-letter index variable. But if the loop is more than a handful of lines of code, use a more expressive name.

Don’t use acronyms and abbreviations. In “Some Studies of Word Abbreviation Behavior” (Journal of Experimental Psychology, 98(2):350-361), authors Hodge and Pennington ran experiments with abbreviations, and found that a third of the abbreviations that were obvious to those doing the word-shortening were inscrutable to others. Thus, abbreviating is a form of encryption, which is orthogonal to our goal of clarity.

There are two exceptions to this rule. Industry-standard acronyms, like “USB”, are fine. Also acceptable are any abbreviations or acronyms defined in a library somewhere – perhaps in a header file:

/* Abbreviation Table* dsply   == Display (the verb)* disp    == Display (our LCD display)* tot     == Total* calc    == Calculation* val     == Value* mps     == Meters per second* pos     == Position*/

Does a name have a physical parameter associated with it? If so, append the units. What does the variable “velocity” mean? Is it in feet/second, meters/second or furlongs/fortnight? Much better is “velocity_mps”, where mps was defined as meters/second in the header file.

One oh-so-common mistake is to track time in a variable with a name like “time.” What does that mean? Is it in microseconds, milliseconds or clock ticks? Add a suffix to remove any possibility of confusion.

The Mars Climate Orbiter was lost due to a units mix-up. We can, and must, learn from that $320 million mistake.

Do you have naming rules? What are they?

Jack G. Ganssle is a lecturer and consultant on embedded development issues. He conducts seminars on embedded systems and helps companies with their embedded challenges, and works as an expert witness on embedded issues. Contact him at . His website is .

9 thoughts on “On names

  1. “”But if we are professionals we must act professionally and do good work for the sake of doing good work.”nStop reading my mind! ^^nIt's always a great pleasure to read your comments.nI use a “mix of rules”: for example, “rtc_isResultCorrect” for

    Log in to Reply
  2. “There is also the variable type to keep track of.nnI once went in to clean up a project that was designed by a committee of people spread all over the world. The unit was large moving equipment that if something went wrong, people might die. The unit wa

    Log in to Reply
  3. “I remember seeing (and using) a convention once where variables started with a lower case letter to indicate type. For instance pBuffer is a pointer where cBuffer is a character and sBuffer might be a string etc. This convention went a long way toward hel

    Log in to Reply
  4. “I once obtained a large FORRAN program with 100+ subroutines, all 7 letters long. The only computer we had that had the graphics program it needed was an IBM; which held to the original FORTRAN standard that required compilers to accept 1-6 character stri

    Log in to Reply
  5. “Thanks Jack, some good rules not only for coding, but for NET NAMING in circuit board design. The only item I would disagree with is use of abbreviations. Some industries rely upon them heavily and are well known. I don't see a problem with using them

    Log in to Reply
  6. “My pet peeve in abbreviations is the use of no for number. Is noElements no elements, a boolean, or the number of elements, a quantity? If I shorten number, Iu2019ll use numElements.”

    Log in to Reply
  7. “Thank You Jack!nnThat is, why I love Ada:nnWhen I define two different, incompatible types like thisnn type Meters_per_second is new float;n type feet_per_minute is new float;nnand two variables:nn vertical_speed_mps : Meters_per_second;n

    Log in to Reply
  8. “Programmed in FORTRAN WATFIV-S on a Sperry Univac 9000 at WPI using punch cards. Next year, our programming work was done on a Data General “Crashmatic” using FORTRAN-77. That mainframe went down so frequently, I wished the Sperry machine was still ava

    Log in to Reply

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.