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:
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
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?
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.