How to Write Comments

Denis Krukovsky writes "Should I write comments? What is a good comment? Is it possible to comment a class in 5 minutes? See " Everybody knows that good code is self documenting- which is why my prof in college demanded we write in Ada. I instead suggest commenting in haiku.

Comments

Check out Rob Pike's thoughts on code commenting

[podz]

Rob Pike, a former powergeek at ATT&T labs, and a present powergeek at Google, has the following to say about code commenting. In general, I agree with him.

Re:The why not the how

[rjstanford]

Sorry, but you happened to hit on one of my pet-peeves with non-self-descriptive code. I do agree with your suggestions, mind you, but I see it all the time: functions describing how they work, not what they do. Sorry to pick on you, but in this case why not take:

public bool CheckSmsValue(Account smsAccount)
{

And instead say:

public bool isSmsValueAccurate(Account smsAccount)
{

That way, anyone who glances at the call will know what the function does. In fact, the first one could be checking for existance, non-existance, accuracy, threshold, who knows? Heck, its exactly the kind of function that I could see being called in many different places by people expecting it to be checking different things. Or coder1 adds it in expecting it to check for "positive" as well as whatever else, months later coder2 realizes that it doesn't and adds the "extra check" into it - its a check function, after all, right? And then coder3's code in some far-away place suddenly starts failing because he didn't want that check in the function.

A good name should be an implict contract. The function above should, by that definition, return "true" if it did at least "check" the SmsValue, and "false" if it didn't bother to... not quite what the original intent was. Probably.

Phew. Sorry for the long-windedness.