You may redistribute this newsletter for non-commercial purposes. For commercial use contact jack@ganssle.com. To subscribe or unsubscribe go here or drop Jack an email.

• Editor's Notes
• Quotes and Thoughts
• Tools and Tips
• Freebies and Discounts
• Docs in English
• The Shirley Test
• Happy and Productive
• Failure of the Week
• Jobs!
• Joke for the Week
• About The Embedded Muse

Tip for sending me email: My email filters are super aggressive and I no longer look at the spam mailbox. If you include the phrase "embedded muse" in the subject line your email will wend its weighty way to me.

Last week's "joke" was about an individual's troubles stemming from license plates that read "NULL." Several readers wrote that Radiolab did a take on this here.

Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it.

In the last issue I mentioned the issue of dealing with power transients. Brian Robinson wrote that there's a good take on that on LinkedIn here.

(That URL is 245 characters long. That's long enough to differentiate about 10³⁶⁰ individual objects. Given that there are only 10⁷⁰ protons in the universe one wonders what these web developers are thinking.)

The giveaway is on vacation for the summer.

The quote in the issue 449 was "If you can't write it down in English, you can't code it." Not everyone agreed.

There were two general objections. The first is that English is an imprecise language that is easily abused. It's pretty easy to write sentences that are redundant, recursive, vague and open to multiple interpretations. I agree! But that's no excuse to abdicate our responsibility to correctly document our work. An imperfect though useful solution is to relentlessly edit our written word, to sharpen our intent and to strive for clarity above all else. English might not be an ideal solution, but the perfect is often the enemy of the good.

The second objection was that English is far from a universal language. Wikipedia pegs the number of languages used in the world at as many as 7000. Should a Farsi speaker be required to document in English, which may be a very foreign lingo?

I've had to work on code that was commented in Chinese and other languages. It's a bit jarring for a Westerner to come across:

while(1){            // 這是評論

If clarity is our goal, and it should be, then a Chinese speaker will find that comment much more informative than a phrase couched in, say, English, when that may be constructed in a grammatically incorrect fashion due to the author's unfamiliarity with the language.

At a dinner with executives of a company in the Czech Republic some years ago the president told me of a major problem they were facing. They had several million lines of C code which was all commented in Czech, yet (according to him) there were only 10m Czech speakers in the world. The company's growth was stalled as the pool of developers was very limited.

In my travels I've come across organizations whose policies varied widely. Some had no rules; their code from a plethora of nationalities was documented in numerous languages, and the Babel-like issues were dealt with by constraining certain parts of the code to specific countries. In many, many other cases the rule was to use English, period. For better or for worse. Some of the docs were incomprehensible due to the authors' poor grasp of the language.

I don't know what the right answer is, but do believe that documentation is a vital part of what we do, and poor docs are a risk to the viability of a company. Risk must be managed, so companies should have a policy that mitigates that risk.

In my experience the problems are worse at startups. These companies code for today, not for next week. Documentation is the least of their concerns; nothing overrides shipping ASAP. Generally the companies either fail, in which case the lousy docs don't matter, or succeed/get-acquired. In that case you almost always see a reckoning. The code haphazardly slapped together by a brilliant founder who soon dumps the mess on a raft of new hires becomes the basis for the company's products. It's a mess, "works" (mostly), and acts as an anchor on engineering productivity for years to come. Few outfits dare a rewrite. The technical debt isn't reflected (directly) on the balance sheet, but it's there, for those in the know.

Harold Kraus sent this ("DER" is Designated Engineering Representative, a person who effectively signs off that the precepts of the avionics standard (DO-178C) were followed in creating software for commercial aviation):

Somehow the idea of using Latin, a dead language, to make this point is both fun and ironic.

Responding to my comment in Muse 450 about Shirley, the young tester who could always break our code, Steve Wheeler wrote:

Daniel McBrearty also responded:

And this from Lous Mamakos:

"Since we started letting the developers use the [chaos, Capability Maturity Model, Personal Software Process, Test-Driven Development] process they have been much happier and more productive."

Really? I can't tell you how many managers have told me some version of this story. It's almost always complete nonsense.

Without productivity metrics it's impossible to know if the team is getting better or worse. Few firmware groups measure anything related to performance. Or quality. There are lots of vague statements about "improving productivity/quality," and it's not unusual to hear a dictate from on-high  to build a "best-in-class" development team. But those statements are meaningless without metrics that establish both where the group is now, the desired outcome, a path to get there, and metrics to determine if the team is meeting these goals.

Some teams will make a change, perhaps adopting a new agile approach, and then loudly broadcast their successes. But without numbers I'm skeptical. Is the result real? Measurable? Is it a momentary Hawthorne blip?

Developers will sometimes report a strong feeling that "things are better." That's swell. But it's not engineering. Engineering is the use of science, technology, skilled people, process, a body of knowledge - and measurements - to solve a problem.

Engineers use metrics to gauge a parameter. The meter reads 2.5k ohms when nominal is 2k.  That signal's rise time is twice what we designed for. The ISR runs in 83 usec, yet the interrupt comes every 70. We promised to deliver the product for $23 in quantities of 100k, and so have to engineer two bucks out of the cost of goods.

Some groups get it right. I was accosted at the ESC by a VP who experienced a 40% schedule improvement by the use of code inspections and standards. He had baseline data to compare against. That's real engineering. When a developer or team lead reports a "sense" or a "feeling" that things are better, that's  not an engineering assessment. It's religion.

Metrics are tricky. People are smart and will do what is needed to maximize their return. I remember instituting productivity goals in an electronics manufacturing facility. The workers started cranking out more gear, but quality slumped. Adding a metric for that caused inventory to skyrocket as the techs just tossed broken boards in a pile, rather than repair them.

Metrics are even more difficult in software engineering. The data is always noisy. The metrics are like an impressionistic painting that yields a fuzzy view.

But data with error bands is far superior to no data at all.

From Daniel Hoenig:

And this pricelss gem from Todd Hayes:

Have you submitted a Failure of the Week? I'm getting a ton of these and yours was added to the queue.

Let me know if you’re hiring embedded engineers. No recruiters please, and I reserve the right to edit ads to fit the format and intent of this newsletter. Please keep it to 100 words. There is no charge for a job ad.

These jokes are archived here.

This is from Will Cooke:

The Embedded Muse is Jack Ganssle's newsletter. Send complaints, comments, and contributions to me at jack@ganssle.com.

The Embedded Muse is supported by The Ganssle Group, whose mission is to help embedded folks get better products to market faster.