Why I like short names for code objects - Embedded.com

Why I like short names for code objects


I am aware that some Longnamers are concerned about my short names. My preference for short names derives from my first job in the computer industry as a logic designer creating complex, hand-drawn schematics. Most signals did not get names, but those that did had to be content with short names, due to limited space. MRQ, memory request, is my all-time favorite name. It has a lot of meaning for me, having used it many times.

I think that long names do have their place for seldom-used objects. For example,
     #define SMX_CFG_HT_SCAN_DUP        0
  #define SMX_CFG_LOCK_NEST_LIMIT    5
  #define SMX_CFG_PROFILE            1
  #define SMX_CFG_SAFETY_CHECKS      1

are much better than
     #define SMXC_HSD                   0
  #define SMXC_LNL                   5
  #define SMXC_PR                    1
  #define SMXC_SC                    1

However, for frequently used objects, short names work just as well and take less space, thus producing more readable code. For example,

     if (bp5 != bp1 || cp5->size != 1488 || smx_bin[23].ffl != cp4  
     || cp4->ffl != cp3 || cp3->ffl != cp2)
          ts_pass = FALSE;

is more readable than,

     if (block5_ptr != block1_ptr || chunk5_ptr->chunk_size != 1488 ||
        smx_heap_bin[23].free_forward_link != chunk4_ptr ||
        chunk4_ptr->free_forward_link != chunk3_ptr ||
        chunk3_ptr->free_forward_link != chunk2_ptr)
             ts_pass = FALSE

In the first example one can clearly see the pattern of one chunk pointing to the next. It would be pretty easy to see a error in that pattern. That would be not so obvious in the second example. The first example is from a heap regression test where the same block and chunk pointers are used hundreds of times. After going through a few tests, one well knows bp5, cp3, and all of their kin. Embellishing them with long names would achieve no benefit. And multi-line statements, as in the second example, push other statements off the screen, thus requiring more up and down scrolling to get a complete picture of the code.

Excessively long names can be detrimental to good code. Here is an example from a chip vendor's header file:

     /* WORD0 Bit Fields */
     #define CAN_WORD0_DATA_BYTE_3_MASK    0xFFu
     #define CAN_WORD0_DATA_BYTE_3_SHIFT   0
     #define CAN_WORD0_DATA_BYTE_3(x)
     (((uint32_t)(((uint32_t(x<     &CAN_WORD0_DATA_BYTE_3_MASK)

Over 50% of the above information is redundant relative to the shortened name version, which follows:

     #define u32 uint32_t
     /* WORD0, DATA BYTE3 Bit Fields */
     #define CAN_W0B3_MSK                 0xFFu
     #define CAN_W0B3_SH                  0
     #define CAN_W0B3(x) (((u32)(((u32)(x)) << CAN_W0B3_SH)) &  

These particular name choices could probably be improved, but the important thing to see is that the CAN_WOB3(x) definition is now easier to read. (Though I wonder if the type casting is excessive.) Excessively long names are used in this header file even for individual register bits. This is problematic when forming logical combinations of them. Considering that code that is easier to read is more likely to be correct, I think these excessively long names actually create more harm than good. I wonder if people are creating them thinking that “it is the right thing to do.”

SMX User’s Guide and Reference Manual

Ralph Moore , President of MicroDigital , graduated with a degree in physics from Caltech. He spent his early career in computer research. Then he moved into mainframe design in the 60's and became a consultant in the early 70's. He taught himself programming and became a microprocessor programmer. He founded Micro Digital in 1975, and many years of successful consulting led into architecting and developing the SMX kernel in 1987. For many years he managed the company’s business and sales, but in recent years he has been focused almost solely on v4 development of the SMX multitasking kernel.

12 thoughts on “Why I like short names for code objects

  1. “While I admit I find excessively long (yeah, talk about a subjective measure) names annoying, I find that the above examples would require some sort of decoder ring. Anyone who doesn't look at that code everyday (or has long breaks between code exposure)

    Log in to Reply
  2. “I agree that short names are okay. But make sure the abbreviations are spelled out where their declarations are defined or some other convenient and maintained database.”

    Log in to Reply
  3. “Wow. I hope I'm not the only person thinking that the example code needs much better formatting and the addition of parentheses to permit better reading and ensure proper order of operations, if not on this version, but if later someone needed to add som

    Log in to Reply
  4. “I agree entirely about that style for multiple tests (etc.), in particular also the use of each test in its own parenthesis. Without those, some tests may well fail subtly and may well be missed.nnFWIW, for readability and intelligibility, I virtually n

    Log in to Reply
  5. “In my experience, short names are a pain..nnIf you work constantly with the same code base,nI guess they could feel or be OK. However, when the codenbase and size of a project increase, involving more nand more developers and libraries, it gets tough

    Log in to Reply
  6. “====================================================================nn if (bp5 != bp1 || cp5-&gtsize != 1488 || smx_bin[23].ffl != cp4 n || cp4-&gtffl != cp3 || cp3-&gtffl != cp2)n ts_pass = FALSE;nn=====================================

    Log in to Reply
  7. “Hi,nnI want to thank you and others for commenting. I probably picked a wrong example to illustrate the point I was trying to make. It is from a heap regression test. My two priorities when writing test code are: to make testing as complete as I can and

    Log in to Reply
  8. “Glad we agree on local variables. I agree your formatting of the long version looks better, but I prefer the short version. I think there is nothing wrong with using operator precedence, within reason. For algebraic expressions, we write a*b + c*d, not (a

    Log in to Reply
  9. “I fully agree. In my non-test code:nnu32 smx_bin_tries; /* bin tries counter for best fit */nBOOLEAN smx_heap_stats; /* enables heap stats */nBOOLEAN smx_chunk_merge; /* free chunk merge mode */nnIt is so easy in the editor or deb

    Log in to Reply
  10. “I agree that longer names are needed for larger projects. In general, I think less familiar names need to be longer, but they do not need to be super-long as some of the examples I gave. I think it is ridiculous that in these examples, the first 20 charac

    Log in to Reply

Leave a Reply

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