/* no comments (part II) */

In a previous installment, I discussed the quality of English in comments, arguing that the quality of comments influences the reader’s judgment on the quality of the code as well.

That’s not the only thing that can make code harder or easier to understand. Today (anyway, at the time of writing), I was working on something where arbitrary-looking constants would constantly come up. I mean, constants that you wouldn’t know where they’re from unless there’s a comment. A clear comment. Let’s see some of those.

/* 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.

Avoiding the Junkyard

Developing software isn’t easy. No, I’m serious. It’s not. Every year that passes brings us more experience, and sometimes reality bites us real hard in the ‘rear.

For example, people do not always remain with a project until it completes. Often, people join a team for a summer, or for a year or two, then leave. That’s normal and expected. Of course, if the project is large, or the stay short, the code portion that was assigned to a particular individual may not be completed by the time he leaves. Can you manage to leave a team gracefully?