Go here to sign up for The Embedded Muse.
The Embedded Muse Logo The Embedded Muse
Issue Number 431, October 4, 2021
Copyright 2021 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 info@ganssle.com. To subscribe or unsubscribe go here or drop Jack an email.

Contents
Editor's Notes

SEGGER Embedded Studio cross platform IDE

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.

Quotes and Thoughts

 The relentless accretion of code over months, years, even decades quickly turns every successful new project into a legacy one. - Grady Booch

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.

Daniel McBrearty:

Re tools - a quick mention for the Saleae product range. (I know I'm not the first.) Why?

They really took time to get the user interface on the app right. It's so good. And the ability to write your own protocol decoder is *really* good. I did a project a few years ago that used an obscure serial control protocol called XY2-100 (from memory) - not complicated or particularly fast, just sync, clock and two data lines - but being able to make a decoder which then would display the values being sent for each frame was such a godsend. It took a bit of fiddling to get it going, maybe a day of work, and Salae had to help me, but they were really responsive and helpful.

I've used both the little budget version with 4 pins (very handy for projects with I2C or whatever) and the full blown one, they all worked very well for me.

Nowadays and FPGA or embedded product that I would design, I would put a port for a Saleae with main signals and a few spare "debug" pins on it.

Timesys has a paper about security in embedded systems. The links in it are particularly useful.  

The Cool Product in the last issue is TI's MCF8316a brushless DC motor driver. It is capable of sourcing/sinking 8A on each of the three outputs. Paul Carpenter noted that the PCB traces need to be pretty beefy to handle these loads.

The datasheet talks about the PCB requirements. I of course is the current sourced and rDS(on) is the resistance of each of the device's internal motor drive FETs:

The device thermal pad should be soldered to the PCB top-layer ground plane. Multiple vias should be used to
connect to a large bottom-layer ground plane. The use of large metal planes and multiple vias helps dissipate
the I2 × rDS(on) heat that is generated in the device.

To improve thermal performance, maximize the ground area that is connected to the thermal pad ground across
all possible layers of the PCB. Using thick copper pours can lower the junction-to-air thermal resistance and
improve thermal dissipation from the die surface.

Also:

Note that rDS(on) increases with temperature, so as the device heats, the power dissipation increases. Take this
into consideration when sizing the heatsink.

They spec rDS(on) at 125 mΩ at 25° C and 1A. At 150° C that rises to 190 mΩ. But the datasheet is silent about this parameter as currents go from 1A to the possible 8A.

This, of course, is an issue any time large currents must be handled on a PCB. Millennium Circuits has a good primer on calculating trace widths. From that site:


Freebies and Discounts

 Zeroplus has graciously given us three of their Wirecare AC circuit testers which I reviewed here. Three lucky winners will each get one of these: 

Enter via this link.

More on Grammar

The notes on grammar in the last issue, particularly its use in comments, generated a lot of discussion. Too much to cite here, but these are some of the responses.

Dave Telling: noted "Lets eat grandma" is not the same as, "Let's eat, Grandma!" Similarly, Clyde Shappee shared this link to examples of punctuation fails, and notes "Remember, the difference between Man's laughter and Manslaughter is only a lowly apostrophe." (I guess that's true for carefully crafted code that ignores spaces...)

I'm reminded of Lynne Truss's book "Eats, Shoots & Leaves". Leave out the comma and you get an entirely different sentence. Then there's "My three favorite things are eating my family and not using commas."

Steve Wheeler wrote:

Language evolves.

That's a justification I hear a lot when I try to explain the importance of grammar and spelling. Unfortunately, I believe that "devolves" is a more appropriate description for what's going on. I ran across a somewhat dismal prediction a couple of decades ago, "Make it possible for programmers to write code in English, and you will discover that programmers can't write in English."

I spent more than 30 years as a programmer, and, if there's one thing I've learned about programming, it's that precision in communicating your intent to the computer is paramount. Natural languages, such as English, are incapable of that level of precision. English is, however, capable of much finer gradations of meaning than are now commonly used, or even understood. What I've seen across that span of time is that very few can write in proper and correct English, and it's been getting steadily worse.

Some of that is because of the rise and dominance of visual media such as television and movies. Harlan Ellison, in the introduction to one of his books (Strange Wine, if memory serves), included an anecdote about a high school student whose reading ability was so limited that she explained to her teacher that movies and television were better than books, because you had to "make up" most of the story when you read, but movies and television gave you the whole thing. Another part of the decline appears to be a general trend toward getting rid of objective standards, and toward elevating feelings over facts, both of which are introducing more and more uncertainty and imprecision into our tools of communication. There was actually an education fad some time ago for teaching English by having students write stories, but the idea was that in order to promote creativity and avoid discouraging the students from continuing, the teacher shouldn't critique their spelling or grammar. How does one improve without feedback?

I see so much misuse of homophones and words that aren't homophones, but are spelled similarly ("I win, you loose!" and "Turn her lose!"), mangled aphorisms (such as the nonsensical, "If that's what you think, you've got another thing coming."), improper verb conjugations ("had went" is distressingly common), and more. Such things are omnipresent, even in books and news media that are purportedly proofread.

So, to directly answer your question, yes, I feel that proper grammar and word choice are important, even in comments. Do I think the situation is likely to improve? Unfortunately, no.

Mike Gilmer shared a tail tale:

I'm an electrical engineer who writes a lot for various professional and hobby-related reasons and over the years I've become very critical of my own work - SMS, online or otherwise.  Likewise, I cannot easily "ignore" others' mistakes I come across. I actually feel it's rather rude to write poorly and publish - even online.  You expect someone to read your drivel? Clean it up!

I would vote that "Yes, it matters how comments are spelled."  Imagine there's an issue in some code - code you didn't write - and you are trying to use CTRL-F to find comments that might, by chance, happen to refer to the troublesome part of the code, but the comments were misspelled such that you get no hits.

About 15-20 years ago, I inherited (admittedly by my own doing) a product (with an 8051) from a recently-defunct subsidiary for which the processor had been EOLed (OK, is that a word?) and a not-quite-drop-in replacement was available. The company wanted the product line maintained. Being an old 8051 guy, I got the replacement design working in just a day or so (happy dance) but then the product was "mine". OK, fine.  Digging through the code, over the next few weeks and months as we enhanced the design, I found I was trying to use the built-in RS232 remote command set.  One such command was clearly meant to be the word PRIVILEGE, however it was coded as PRIVILEDGE.  So... do I think even a little bit about correcting the spelling? Of course not. It would break our internal factory test/cal software (and anyone else's).  So this "crooked painting" stared back at me every time I went into that file.

Dan Daly commented:

Is proper grammar an anachronism?  Not on my watch.

Should comments in code have proper spelling and grammar (and punctuation)?  Yes, yes, a thousand times YES.

I admit that I have a well-deserved reputation as an acute (some might say anal) stickler for such things.  I go one step further and treat misplaced brackets, extraneous spaces, and other such things (which many engineers seem to want to overlook) as misspellings, and call out every one of them in code reviews.

Words matter, letters matter, punctuation matters; "let's eat Grandma" is not equal to "let's eat, Grandma", no matter how many times the author says "you know what I meant".

Coding is at its base a literary exercise, and we live in a world where misspellings in that literature renders billion-dollar spacecraft useless.  We pride ourselves (or should) as master craftspeople; that high level of attention to detail can and must extend all the way to the lowly comment.

Pete Wilson is pretty adamant about proper English in comments:

>Do you think that even comments in code should have proper spelling and grammar?

Hell, yes.

First, suppose I speak the same language as the author. Then I want a clear comment, well-constructed, that has no ambiguities. Because I want and need a single, correct, description of what the code is supposed to do.

Suppose I don't speak the same language. How am I better served by meaningless - or worse, ambiguous - babble?

Finally, suppose one day we get a system which really can understand written "English".
Then it can check that the semantics of the code at least approximate the intent of the comment. [Yes, this'd be for archaic code - given machinery like that, one can imagine a somewhat different approach to programming..]

Jeremy Overesch wrote:

In the latest embedded muse you mention the importance of grammar in comments. I tend to agree.  However, I prefer to have variables with actual names, rather than just terribly shortened names like "tpint" for "temporary pointer to int" or function names called "Update". What is the pointer actually used for? What's actually getting updated? Long gone are the compilers that have a 32 character limit.  Even if there is a 32 character limit, useful variable/function names can definitely fit into that space. The names themselves should be meaningful, so I don't need to depend on out-of-date comments to figure out what's happening.

However, I'm not discounting comments entirely. They are still required for complex bits of code. I find that the most helpful comments are *why* something is being done. Much of the time, figuring out what is happening isn't the hard part, but why it was done the way it is. Unfortunately I tend to see that people who write incomprehensible code also write incomprehensible (or not very helpful) comments.

In regards to your comment about tools doing spell checking, I find that Clion does this quite well. It scans comments for spelling errors as well as most recently adding grammar checking. It also has good checking for actual code. It can be configured to automatically check for variable name conventions, such as CamelCase and snake_case, considering the case changes, underscores, etc. as word breaks, and calling out accordingly.

If one is looking for a free tool, Microsoft's VSCode also has multiple spell checking extensions, like "Code Spell Checker" from Street Side Software. I haven't used it as much, so I cannot speak fully on its capabilities.

Mat Bennion shared an editor that checks spelling:

You said: "Our tools are primitive. How I wish for an editor that checked comments, and only comments, for spelling!"

This is from TI's Code Composer Studio, now a fairly old version:

Spell checking only in the comments!

Stephen Bernhoeft did as well, in this case in Netbeans:

Thank you for your article dealing with the issue of grammar. In response to the plea "...How I wish for an editor that checked comments, and only comments, for spelling!"

I offer the following screen-shot from MPLAB X IDE. Netbeans has this feature. (Eclipse might have this also ?)

From Michael Vos:

An old joke on grammar:
Before I went to University (College) I wanted to be an Engineer. Now I are one.

A good book to read: "A GRAMMAR OF THE ENGLISH LANGUAGE, IN A SERIES OF LETTERS" by WILLIAM COBBETT.
Pub: CAMBRIDGE UNIVERSITY PRESS, 2014. First published in 1819.
ISBN: 978-1-108-06994-6 Paperback.

Jon Titus laments the loss of editors, people editors that is:

When I worked at EDN magazine we technical editors handed our article drafts to people on our staff called primary editors.  Those editors had language skills most engineers did not and they edited and reworded articles so they remained accurate but used proper grammar, punctuation, and so on.  At times a technical editor would say, "But the readers will understand what I mean..."  That objection carried no weight with the chief editor.  The primary editors had the final say in language matters and improved almost every article and column.  Engineering jargon and made-up-words had no place in our magazine.

I vote for clear, accurate, helpful comments with correct spelling.  And I suggest writers use the active voice.

Kirk Bailey agrees:

Add my "amen brother" as a response to your comments on grammar. You mentioned comments, but what irks me even more is when a misspelling appears in something like a variable or function name. This may be harder to fix because some organizations may view the fix as a "code change" whereas fixing a comment is not so viewed. I've worked with people that have very poor spelling and flinched at the mangled names they came up with in code. Whenever possible, I tried to force a fix, but that wasn't always possible.

Vlad Z agrees about the importance of spelling and grammar in prose, but has a different take on comments:

Comments, IMHO, is a special case.  It's not a literary work.  Information should be delivered clearly and unambiguously, but it does not mean King's English should be used.  I can accept a comment such as this:

                x = f_x( null, x ); // use the side  effect

I do not approve of side effects or their use, but the comment clarifies the reason for the seemingly unrelated call.

I can also accept a comment that drops vowels since in English it's the consonants that carry the meaning.

Gene Schroeder sent this:

You probably have gotten many responses to your wish for an editor that could check only code comments for spelling. In emacs, the common spell checker command is "ispell" but we also have "ispell-comments" that does what you want. Additionally, there is "ispell-comments-and-strings" which also checks literal strings.

It is especially handy in preparing for code reviews, where spelling errors are always found!

R N Crorie wrote:

It is, but it shouldn't be.   I can live with the US and the UK being two countries separated by a common language(!), and I accept that all language evolves, but the rate at which English (US or UK) is evolving makes me think of a crazy uncontrolled evolution of an aggressive tumour - or (I think) "tumor".

Language conveys meaning, and imprecise language conveys meaning imprecisely.  The misuse of "may" (permissive) when "might" (probabilistic) is required is something I've learned to overlook, but discovering that the British Broadcasting Corporation has now ceased using the word "whom", wrongly preferring "who" as an inappropriate substitute because "the Corporation prefers a style that is widely readable" (= "people are too stupid nowadays to get it right or even understand the difference") is just too much to bear: even when it publishes something containing factual errors, the Corporation often states that other media sources are getting the same thing wrong, so it doesn't matter.  Really!

Maybe I'm just getting old.

Old Magazines

David Laurence sent a link to an amazing site that has hundreds (at least) of old radio magazines with thousands (at least) of issues in .PDF format. I pass this along a little reluctantly as it may prove to some to be a curse, an infinite time sink. But it sure is fun to browse.

The first chunk of magazines are more the business of radio; scroll down to the "Technical" section for a great romp through what is effectively the history of electronics told in terms of the trade and popular press of those long-ago decades.

Here are a few examples from just the January 1949 issue of Radio Electronics. Old timers will remember how even into the 1960s the popular electronics magazines had dozens of these ads promising good careers in TV servicing.

Then there are the TV ads. This is for a TV with a huge three inch screen! That $100 unit is $1140 in today's dollars. Note that an optional magnifying glass was available.

This ad, from Heathkit, pushes WWII surplus equipment. As a teenager in the 1960s we still had access to boatloads of WWII surplus gear. The costs were vanishingly close to zero, which meant, like so many of us, I played with vacuum tubes long before moving to semiconductors. But the supply was erratic. Working on ham radio moonbounce with a friend I accidentally shorted out the plate resistor on a surplus hydrogen thyratron and the tube blew up. I couldn't get a replacement, which quashed that project.

Fun stuff. We've come so far in such a short time.

Failure of the Week

From Bob Dunlop:

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

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

These jokes are archived here.

I saw my math teacher with a piece of graph paper yesterday. I think he must be plotting something. 

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. We offer seminars at your site offering hard-hitting ideas - and action - you can take now to improve firmware quality and decrease development time. Contact us at info@ganssle.com for more information.