/* no comments (part I) */

Comments have always bothered me. Not that I do not find them useful. It’s that we never know really how to use them properly. They’re also quite hard to maintain so that they follow the current state of the code. Comments tend to be written by the original programmer then never really updated to follow the latest modifications.

In addition to be concise, informative, to-the-point, comments should be written in the most precise language possible, one where words are chosen so that there are no unwanted overtones, no innuendos, and no obscene language. English is the new lingua franca, and this means that comments, in order to achieve collaboration with as many different people as possible, must be written in English. That might be a problem when you’re dealing with non-native speakers.

Of course, comments aren’t meant to be great literature passed down to countless generations, but they should be written in this kind of international English—no, that’s not American English—devoid of memes and other cultural references. It has to be informative, precise, and also understandable by the next programmer, whether he’s also <insert your ethnic group here> or not.

The last thing you want is to write comments in engrish (for examples, see [1,2] and Engrish Funny). If the effect is temporary rather amusing, it is incredibly detrimental to your code in general.

The reason why it is very detrimental is a psychological one. If you read comments that are written in ludicrously bad engrish, you will think that the associated code is also ludicrously bad, regardless of its actual quality. I’m sure you’re thinking “no I won’t” but the thing is that yes, you will. And very much so if compounded with other commenting problems.

*
* *

Comments are one of those things I still do not quite know what to do with. First I always try to make my code readable without comments by very carefully choosing the objects names as to be as descriptive as possible and by structuring code in way that my intent is clear. Still, you still need comments to communicate your mindset to the next programmer. Maybe he doesn’t know about about compact tree storage in a flat array; I can’t suppose he does. Maybe he’s a junior, maybe not; maybe he does know about them and he think it’s stupid to use that trick here: the comment must complement the code in describing my intent and validating design decisions.

In any cases, the comment must be written in perfect English, without unwanted overtones, limiting itself to exactly what you want it to say. I know, easier said than done!


[1] Charlie Crocker — Lost in Translation: Misadventures in English Abroad — Callistemon Books, 2007

[2] Charlie Crocker — Still Lost in Translation: More Misadventures in English Abroad — Random House Books, 2007

4 Responses to /* no comments (part I) */

  1. Okay, so here is a comment without any unwanted overtones:

    What is the sound of one hand clapping?

    I hope you will know what to do with this comment…

    Best

    Arne

  2. Yeah, I needed that smack!

    Best

    Arne

  3. […] a previous installment, I discussed the quality of English in comments, arguing that the quality of comments influences […]

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: