embedded software boot camp

On the use of correct grammar in code comments

Saturday, April 11th, 2009 by Nigel Jones

Back when I was in college the engineering students were fond of dismissing the liberal arts majors by doing such witty things as writing next to the toilet paper dispenser “Liberal Arts degree – please take one”. One of the better retaliatory pieces of graffito that I really liked was: “Four years ago I couldn’t spell Engineer – now I are one”. I think this appealed to me because there was more than a smidgen of truth in its sentiment. If you don’t believe me, just take a look at the comments found in most computer programs. I don’t think I’m being exactly controversial by noting that most comments :

  • Lack basic punctuation.
  • Contain numerous spelling errors.
  • Liberally use non-standard abbreviations.
  • Regularly omit verbs and / or other basic components of a sentence.

As a result, many comments are nonsensical. In fact I’ve been in situations where the comments are so badly written that it’s easier to read the code than it is the comments. Clearly this isn’t a good thing! When I question programmers about this, I typically get a shrug of the shoulders and a ‘what’s the big deal’ attitude. When pressed further, the honest ones will admit that they couldn’t be bothered to use correct grammar or spelling because it’s too much effort – and after all you can work out what they mean if you just try hard enough. They are of course correct. However taken to its logical conclusion, this is really an argument for not commenting at all – since with a bit (OK a lot) of effort it should be crystal clear what the code is doing (and why) simply by examining it.

I decided to write about this now since I recently heard from Brad Mosch concerning a pet peeve of his. He gave his permission for me to quote from his email:

I see all the time mixed occurrences of whether or not a space is used for things such as 3dB, 3 dB, 1MHz, 1 MHz, etc. I am hoping that someone in the embedded guru world propose that a space is ALWAYS used between the number and the unit of measure. That is the documented standard that was used in our technical writing at United Space Alliance and NASA. The funny thing is, even though that standard existed out there at Kennedy Space Center, not a whole lot of people knew about it because I saw the same problem in documents out there all the time. Anyway, my point is, isn’t “1 Hz” a lot more readable than “1Hz”?

I’m sure many of you may think that Brad is being overly picky. However I don’t. His real point (in the last sentence) concerns readability. If you are going to write a comment surely it should be as readable as possible? Now I consider myself a very conscientious commenter of code, and so as a matter of interest I did a quick search on my current project to see whether I was following Brad’s advice. Well I was – about 90 % of the time. I found that my style depended a bit on the units. For example, I always appended the % sign without a space, whereas mV, mA etc just about always had a space between the value and the units. You’ll be pleased to know Brad that I’ll be mending my ways!

Anyway, I’ll leave this topic for now. Next time I visit it I’ll tell you how I spell check my comments. Hopefully having read this post you’ll know why I do it.

10 Responses to “On the use of correct grammar in code comments”

  1. Gauthier says:

    One of the best comments I’ve seen:”Added after meeting with XXX 2005-13-14″Dates like 06-05-05 are irritating, I never know if it’s 6th of may, 5th of june, 5th of may 2006…But this??

  2. Alan Bowens says:

    Personally I always write the units immediately following the value (e.g., “3MHz” as opposed to “3 MHz”. The reason is that if/when the code ever gets turned into documentation, whether automatically or handraulically, Word et al love to turn that little space into a line break. And so you end up having to search through all of the documentation, converting all such spaces into hard spaces. A personal thing, perhaps, but at least I’m consistent.I’m firmly with Nigel on the whole spelling/grammer issue; see this blog entry for my comments on comments.

  3. Nigel Jones says:

    Alan: I just went and read your blog entry – it’s excellent and also very witty. For those of you who are unsure as to whether it’s worth the click – trust me it is.BTW you also beat me to the punch on a planned future blog posting. I too spell check my code. I’m glad to know that I’m not the only ‘weirdo’ out there. I guess I can still talk about how I do it (a combination of a Perl script and aspell). How do you do it?

  4. Erik Shreve says:

    Nigel,I spell check my code as well. And often encourage the team I work with to do the same. I’d be interested in hearing details of your script.Personally, I have found Source Code Spell Checker from Softario to be handy.http://www.softario.com/scsc.htmlThe price is steep (in my opinion) but the free version simply limits the number of files you can check in a single project. Many modern IDEs also have spell checkers built in. I currently use SlickEdit 2008 at work and it has a spell check feature (just not quite as good as Softario’s). I believe Eclipse has spell check plugins available as well. Erik ShreveP.S. I appreciate your drive for professionalism and quality in our field. It keeps me coming back to read more.

  5. Anonymous says:

    Alan, Nigel:Couldn’t agree with you either of you more. To me, the anecdote about the pipe fitter is spot on. Clean comments and good style (ie consistent style) signify quality work. Whenever I see these I inherently assume that the programmer knows what they are doing.As for spell-check tools, all projects that I am in charge of have the tool SCSC from softario.com run over them on a weekly basis. Not a free tool, but has paid for itself in the time since I bought it in my opinion.

  6. Allen Moore says:

    Thanks for the pointer to Softario’s SCSC. I’m always on the lookout for better static checking tools, and I hate spelling errors as much as the next perfectionist. Interestingly, I found a spelling error on their web page, which they cheerfully fixed as soon as I pointed it out to them.

  7. Nigel Jones says:

    Thanks for the link to Softario. If I’d found this then I probably wouldn’t have come up with my own solution. Details to follow in a Blog posting soon!

  8. Alan Bowens says:

    Hi Nigel,I've just come across this blog entry again, sorry I didn't reply sooner – like eight months ago, when you asked the question :)I actually use Source Code Spell Checker from Softario too, and am glad to see there are other users out there. It's also reassuring to see that other people go that little bit further too.

  9. BTL says:

    “On the use of correct grammer in code comments” – You mean “grammar”? 😛

Leave a Reply