Embedded Muse 117 Copyright 2005 TGG October 4, 2005

You may redistribute this newsletter for noncommercial purposes. For commercial use contact jack@ganssle.com.

EDITOR: Jack Ganssle, jack@ganssle.com

- Editor’s Notes
- Engineering Washouts
- Variable and Function Naming
- Jobs!
- Joke for the Week
- About The Embedded Muse

Editor’s Notes

Did you know it IS possible to estimate software schedules accurately? Do you want to increase your team’s productivity? Reduce bugs? Meet deadlines? Take my one day Better Firmware Faster seminar. You’ll learn to thwart schedule-killing bugs, manage reuse, build predictable real-time code, better ways to deal with uniquely embedded problems like reentrancy, heaps, stacks, and much, much more.

I’m presenting this on two dates:
- Chicago, IL on December 5
- Irvine, CA on December 7

Want to be your company’s embedded guru? Join us! There’s more info at https://www.ganssle.com/classes.htm , including cheap flights to these cities from around the USA.

If your outfit has a dozen or more engineers who can benefit from this training I can present the seminar on-site. See https://www.ganssle.com/classes.htm .

Engineering Washouts

Richard Andrews passed along Douglas Kern’s epistle about being a washout from engineering college (http://www.techcentralstation.com/092105B.html ). It’s well-written and brutally honest. Mr. Kern was apparently a very smart student who failed miserably at his semester and a half attempt to become an engineer. He fears the US’s competitiveness will be destroyed by an inadequate number of engineers, and worries that the fault lies with teachers who can’t teach and professors who use absurd boot-camp courses to weed out anyone with an IQ under 150.

The article makes for uncomfortable reading. When I went to school decades ago those same sorts of instructors obfuscated more than enlightened. Language barriers compounded by clueless teachers kept the college crowd in a continual level of bafflement. I never really understood the math till the next semester, yet mandated physics and engineering classes used the math we were supposed to learn tomorrow today.

In the transistor theory class the teacher – a tenured full professor - wrote the transfer function of an amplifier on the blackboard. The decaying exponential puzzled me so I asked, “Does that mean the output of my stereo will fall to zero over time?” He studied the formula for a minute, replied “I guess it does,” and blissfully carried on.

I remain mixed on the math. In a 30 year career it’s rare that I’ve needed even the most elementary calculus, and have never solved a differential equation since my university days. Yet those classes did give insight to certain engineering and physics problems. But today my 18 year old knows more calculus than I remember, despite my accumulating almost enough credits for a math degree.

Engineering education certainly shouldn’t be dumbed-down. But the current practice of hiring and promoting teachers based on their research and PhD credentials is fatally flawed. Teaching comes first, but teaching is a difficult and critical skill seldom taught to engineering professors.

I see a strong parallel between academia and industry. Very bright technical experts become instructors with no formal teaching education, just as engineers get promoted into management without any management schooling. Yet all of these skills – teaching, engineering, and management - are careers unto themselves. Few of us learn anything about management or teaching except for what we manage to garner in on-the-job training. Yet we’d never hire an MBA or fry cook and park him down in front of a computer, departing with the words “OK, now write the signal processing code.”

Variable & Function Naming

The Boston Embedded Systems Conference in September was, as usual, an interesting and fun experience. I try to sit in on a class or three at each of these events, and managed to attend Jean LaBrosse’s seminar about firmware standards.

Now there’s a guy who can teach!

Though standards are an important part of making fabulous firmware the subject is rather dry. But not in Jean’s class. The packed room was raptly attentive, with the exception of one moron chatting loudly on a cell phone.

Though I’ve promoted standards for a long time I picked up a couple of good ideas about naming functions and variables, and will shamelessly share them here.

First, names should start with the big and work to the small. An example is: Universe_Galaxy_SolarSystem_Planet. For example:


is better than:


If you were looking through a dictionary or link map that lists variable names, you’re more likely to focus on functions related to the timer, rather than to initializing things. So for a timer we might find:


Obviously, this is, well, obvious. What’s important is that the rule is codified in the standard so everyone on the team uses the same, highly readable, convention.

Secondly, never use acronyms and abbreviations as part of a variable or function name, unless such acronym/abbreviation is defined in the code in a special abbreviations table, or if it’s an accepted industry convention like LED, LCD, and CRT.

Clarity is our goal! Where “Disp” might mean display (as a verb) to you, to someone else it might imply a chunk of hardware. “Enc” could be encode or encoder.

An example Abbreviation Table is:

/* Abbreviation Table
* Dsply == Display (the verb)
* Disp == Display (our LCD display)
* Tot == Total
* Calc == Calculation
* Val == Value
* Pos == Position

I’ve amended my firmware standard (at https://www.ganssle.com/fsm.htm ) to reflect these ideas.

If you care about writing beautiful code, do take Jean’s class.


Joke for the Week

Short of an apt phrase for the annual appraisal of your staff? Try some of these for size (reputedly from Royal Navy Officer Fitness Reports):
1. His men would follow him anywhere, but only out of curiosity.
2. I would not breed from this Officer.
3. This Officer is really not so much of a has-been, but more of a definitely won't-be.
4. When she opens her mouth, it seems that this is only to change whichever foot was previously in there.
5. He has carried out each and every one of his duties to his entire satisfaction.
6. He would be out of his depth in a car park puddle.
7. Technically sound, but socially impossible.
8. This Officer reminds me very much of a gyroscope - always spinning around at a frantic pace, but not really going anywhere.
9. This young lady has delusions of adequacy.
10. When he joined my ship, this Officer was something of a granny; since then he has aged considerably.
11. This Medical Officer has used my ship to carry his genitals from port to port, and my officers to carry him from bar to bar.
12. Since my last report he has reached rock bottom, and has started to dig.
13. She sets low personal standards and then consistently fails to achieve them.
14. He has the wisdom of youth, and the energy of old age.
15. This Officer should go far - and the sooner he starts, the better.
16. In my opinion this pilot should not be authorised to fly below 250 feet.
17. The only ship I would recommend this man for is citizenship.
18. Works well when under constant supervision and cornered like a rat in a trap
19. This man is depriving a village somewhere of an idiot.
20. Only occasionally wets himself under pressure.