For novel ideas about building embedded systems (both hardware and firmware), join the 40,000+ engineers who subscribe to The Embedded Muse, a free biweekly newsletter. The Muse has no hype and no vendor PR. Click here to subscribe.

By Jack Ganssle

No Cute Code

Published 2/25/2004

What do you think of the following construct?

 while (42)
           {
           if (io_buffer[ptr])
           return (io_buffer[ptr++]);
           ptr = 0;
           }

It's part of a putchar() function - provided by the compiler vendor - that I found this week while playing with a cool little 16 bit microcontroller. There were no comments, of course.

The initial while statement threw me for a minute. Why did it take an argument of 42? Obviously 42 is non-zero, so the code is nothing more than an infinite loop. But why 42? Was it a magic number? Was there some meaning to this that eluded me? Perhaps a bifocal-eluding small "i" prefixed the number, turning this into a simple variable.

Eventually the significance sank in. The mice in Douglas Adams' Hitchhiker's Guide to the Galaxy built a grand computer that pondered the question "what is the answer to life, the universe, and everything" for ten million years before answering: "42." That answer meant as little to the mice as it does to us, but kept Zaphod Beeblebrox, Arthur Dent and Ford Prefect tumbling into one misadventure after another. While Marvin the depressed robot whined about everything.

The deluded programmer could have used a symbolic notation; it is, after all, generally a Bad Idea to embed numeric constants in the code. Maybe something like:

  while (meaning_of_life_etc)

with a 

  #define meaning_of_life_etc 42

buried in a header file somewhere. That's a lot more disciplined. If the meaning of life, the universe, and everything were to change a quick edit of the header file would fix the program everywhere.

But this is even foggier than the original version. Now we don't know anything about meaning_of_life_etc without searching through dozens of .h files. Is it a constant? Global? Does an ISR change it invisibly in the background?

This reminds me of the time my college assembly-language instructor just about blew a gasket when I submitted a card deck (this was a long time ago) that looked like:

        Read input data1
        Read input data2
        Compute data1 times data2 to result
        Output result

The assignment was to read two inputs, multiply them and print the result. In Univac 1108 assembly language, which of course this code doesn't resemble at all. But that machine had a very powerful macro preprocessor, so, just to be ornery I defined the above constructs as macros. Was it valid assembly? Maybe in some technical sense, but by getting very cute I submitted code that wasn't standard, wasn't maintainable, and that no other programmer could work on.

Some years ago a friend who owned a compiler company told me about an odd experience he had had. One day three burly guys draped in suitcoats showed up. In a Kafka-esque scene they demanded that the company remove a word used as a variable in a demo program supplied with the compiler. but they refused to identify the word. It was classified, it seems, a code word denoting something really important to them but meaningless to my pal. In an odd dance the suits pointed vaguely at listings while looking away. because Jeff wasn't allowed to know this secret. Finally, he figured it out and made the change.

It seems the secret had been revealed in a book about the NSA. "For fun", a young programmer used the word as a variable name. The agency didn't share in the developer's guffaws.

Software has to do two things: it's gotta work, of course. But just as importantly, the code must clearly convey its intentions to the next developer.

Those are basic coding rules. An extra bit of wisdom might be to avoid dispensing national secrets in the source.

And don't be cute.