Go here to sign up for The Embedded Muse.
TEM Logo The Embedded Muse
 Issue Number 319, December 19, 2016
Copyright 2016 The Ganssle Group

Editor: Jack Ganssle, jack@ganssle.com
   Jack Ganssle, Editor of The Embedded Muse

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

Contents
Editor's Notes

Did you know it is possible to create accurate schedules? Or that most projects consume 50% of the development time in debug and test, and that it's not hard to slash that number drastically? Or that we know how to manage the quantitative relationship between complexity and bugs? Learn this and far more at my Better Firmware Faster class, presented at your facility. See https://www.ganssle.com/onsite.htm.
Quotes and Thoughts

"Testing leads to failure, and failure leads to understanding" - Burt Rutan
Tools and Tips

Please submit clever ideas or thoughts about tools, techniques and resources you love or hate. Here are the tool reviews submitted in the past.

I have some comments about comments later in this issue. But here's a head-scratcher: how many comments should code have? In Measuring Software Quality: A Case Study, by Thomas Drake (IEEE Computer Vol. 29, No. 11) the author looks at 25 million lines of code at NSA and finds the best has a comment density (i.e., percentage of non-blank lines that are comments or have comments) exceeds 60%. How does yours compare? A nice free tool that will measure comment density and other metrics is Source Monitor.
Freebies and Discounts

Patrick Mulder and Kelsey Breseman wrote the just-released book Node.js for Embedded Systems (Using Web Technologies to Build Connected Devices. I have not had a chance to read it yet but it looks like a nice introduction to using any of a large number of commercially-available boards and sensors for the Maker scene. The authors generously sent two copies for readers of the Embedded Muse. Enter the contest to be one of two lucky winners of a copy of the book!

Enter via this link.
The Rise of the Machines - Security in the IoT World

A very interesting paper about attacks from IoT devices (Rise of the Machines - The Dyn Attack Was Just a Practice Run) is a long (62 pages) but worthwhile read. The most incisive comment is:

Bruce Schneier wrote on his blog that,"The technical reason these devices are insecure is complicated, but there is a market failure at work. The Internet of Things is bringing computerization and connectivity to many tens of millions of devices appliances, thermostats, light bulbs, fitness trackers, medical devices, smart streetlights and sidewalk squares. Many of these devices are low-cost, designed and built offshore, then rebranded and resold. The teams building these devices don't have the security expertise we've come to expect from the major computer and smartphone manufacturers, simply because the market won't stand for the additional costs that would require. These devices don't get security updates like our more expensive computers, and many don't even have a way to be patched. And, unlike our computers and phones, they stay around for years and decades.

An additional market failure illustrated by the Dyn attack is that neither the seller nor the buyer of those devices cares about fixing the vulnerability. The owners of those devices don't care. They wanted a webcam - or thermostat, or refrigerator - with nice features at a good price. Even after they were recruited into this botnet, they still work fine - you can't even tell they were used in the attack. The sellers of those devices don't care: They've already moved on to selling newer and better models. There is no market solution because the insecurity primarily affects other people. It's a form of invisible pollution.

And, like pollution, the only solution is to regulate. The government could impose minimum security standards on IoT manufacturers, forcing them to make their devices secure even though their customers don't care. They could impose liabilities on manufacturers, allowing companies like Dyn to sue them if their devices are used in DDoS attacks. The details would need to be carefully scoped, but either of these options would raise the cost of insecurity and give companies incentives to spend money making their devices secure."

Since so many IoT devices are designed overseas it's hard to see how regulation would work. But many are arguing for it nonetheless. I suspect no matter how ill-formed these rules may be, at some point we'll be subject to an avalanche of mandates and corresponding certifications. Even if it were free to add perfect security to our designs, validating it will be expensive.

Someone is going to make a bundle in the security validation business.

One recommendation made in the paper is that the software in IoT devices be open source. That strikes me as a non-starter since many products contain valuable proprietary IP; IP that companies have a valid interest in protecting.

So what is the answer? I'm not sure one exists. Yet many vulnerabilities are just stupid, like open telnet ports.

One does have to wonder if using commercial OSes like Linux and Windows in IoT devices is wise, given that they will always present large attack surfaces and most devices never get security upgrades. Is the future going to be the increased use of MCUs running hardened RTOSes? Ironically the electronics industry has made memory so cheap that big operating systems are appealing even for relatively simple devices like CCTV cameras.

A vendor-specific solution merging both a desktop OS and a proprietary RTOS is in this document.

However this plays out it will be on the backs of embedded engineers. If you're building a connected device and not thinking about security, well, that will certainly change.

Comments welcome. Our community probably has more insight into this matter than any think tank or government body. Some previous reader comments are here.
Comments on Comments

I've talked with several engineers recently who told me they don't comment. Ever. Their code is completely self-documenting so comments aren't needed. One argument is that the code inevitably drifts away from the comments, and wrong comments are worse than none at all.

While I agree that in practice the second point is often true, this is unacceptable behavior from supposed professionals. It is an indication of poor craftsmanship. It is our professional responsibility to write reliable, maintainable code - and that includes maintaining the comments. Poor craftsmanship is akin to the mechanic who is careless in replacing the drain plug after an oil change. Jiffy Lube would find that a firing offense.

As to the first point, in my 40+ years in this business I have never seen a non-trivial product that is truly self-documenting. Self-documenting code is generally self-documenting only to the original author.

Do you use in-line comments? The ones like this:

a= out_pr * scale;  // scale the input

… where the comment is appended to a line of C or C++ code.

While these can be an effective way to document code, never fear to use a block comment instead. Comments are supposed to be distinct from the code. Though part of the program, they present the information in a different sort of context, and may be read independently of the code.

Usually we start a project determined to write pretty code, and craft a rule to start all comments in a particular column. That lines things up beautifully, but greatly increases the hassle of maintenance. Change just a single character and you've got to realign the starting pair of slashes. Why force developers to work so hard? Especially when we know, under deadline pressure, we won't?

This artificial demarcation means it's hard to fit a statement in the allotted space before the "//". Sure, it's possible to continue a C statement over multiple lines, but breaking up a statement in a comprehensible way, especially when using long variable names, can be hard. (Yes, some IDEs will do most of that work for you).

With comments appended to the C lines there's an essential tension between keeping the C short so as to not run into the double slashes, and picking a starting line number not so high that all of the comments start in a column waaaay out to the right, pushed off the screen of a reasonably-sized editor window.

The decision to start a line of documentation on, say, line 60, limits the length of the comment. We remove words, context and meaning to fit the comment into the 20 or 40 characters left before the end of the editor window. What should be "disable all safety warnings" gets compressed to "dis warns," leaving some future maintainer wondering why we'd want to dis anyone, let alone a warns, whatever that might be.

I prefer using comment blocks, which are large enough to permit a complete description. So:

/* 
Adjust the input by "scale", which
is the coefficient calculated at
calibration time.
*/

is far better than:

a= out_pr * scale;  // scale the input

In assembly, where each instruction does so little and the mnemonics are short, in-line comments are fine. And in C in-line comments documenting structure members and the like also makes sense. Where there's truly a short message to convey, do append a comment after the line of code. But where more explanation is needed, use a block of comments.

Comments should be active voice. They should be grammatically-correct and complete.

Finally, one of the best things I learned to do when writing code is to write a function's header comments first. Then, write all of the rest of the comments for that function. These constitute the design. Filling in the code is then pretty simple.

Jobs!

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.
Joke For The Week

Note: These jokes are archived at www.ganssle.com/jokes.htm.

Riffing on the very old Pentium FDIV bug:

Q: What is the similarity between a rabbit and a Pentium?

A: They both can multiply, but can't divide !

Advertise With Us

Advertise in The Embedded Muse! Over 27,000 embedded developers get this twice-monthly publication. .

About The Embedded Muse

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.