Code Comments and 5WH


Comments in code, you can’t live with ’em, you can’t live without ’em. Depending on who you ask, comments are a crucial form of documentation without which most source code would be unusable. Others might say that code comments are, at best, an administrative nuisance or, at worst, dangerously misleading as they inevitably lose sync with the source code they purport to clarify. Reality, of course, lies across a spectrum between these extremes. Code comments, in-and-of-themselves, are neither helpful, nor hurtful. It’s the content of the comments themselves and how they relate to the reality of the source code itself that makes them valuable (or potentially harmful.)

If you’ve attended elementary school in the States, you should be familiar with 5WH, the building blocks of questions: Who, What, When, Where, Why and How. These six words cover the gamut of questions you can ask and provide structure to information sharing. So, what happens when you apply these questions to comments in source code and use them to direct the information you need to share?

Who?
Who wrote this code? Or, more importantly, who is responsible for this code when it breaks something? Explicitly identifying the owner of particular bits of code is useful because subsequent readers of the code then know who to ask if they have questions. This goes beyond just code ownership. I actually write my name next to any code comments I make so people can ask me to clarify in case my comment didn’t make sense to them.

That being said, this question can also be easily answered by having decent source control. If I find comments disagreeing with what I see from source control histories, I trust what the source control says.

What?
Commenting about what source code does is absolutely useless. People who hate comments in code usually hate them because they are answering this question. Writing what code does is simply re-stating information presented by the source code itself only with less precision and a greater change of being incorrect. This is also the kind of commenting you’ll get if you instate a commenting policy without addressing what questions the comments are actually supposed to answer.

Do we really need more “documentation” like this:

	//Sets the position of this object
	void SetPosition(Vector2 position);

It’s silly. Don’t do it.

When?
Putting a time-stamp on comments is almost as useful as putting your name on comments. This is another bit of information that replicates information provided by source control but it can help someone reading your code if they can decide, at a glance, whether a given comment is old and out-of-date.

Where?
Where is the code? The code is where the code is. A more useful question to answer is: where should this code be used? If the answer is not obvious, it’s probably worth mentioning. Another useful bit of information is telling the reader where your code came from. If you pulled the code from the net, include a link in the comments to the original material. If you copy-pasted (shame on you) the code from someplace, mention the source in the comments.

Why?
This is the BIG ONE! How often have you found yourself reading someone else’s (or your own) code and thinking: “Why did they do that?” If you answer only one question with your comments, answer this one. While “what” is fully captured by the code itself and “when/who” are captured by source control, “why” is pretty much invisible unless explicitly explained. If you think something is a hack, elaborate on why that is. If there’s some code that you think might be dangerous, explain why. If you chose a particular implementation when another might have worked, talk about why you made that choice. The person reading your code will thank you.

How?
If your code needs some explanation in order to be used correctly or if there is some particular order in which certain functions need to be called in order to behave as expected, it’s a good idea to document that in your comments. This is another question, like “Why”, that is not easily answered by source-control or the source code itself.

Programmers tend to be busy and comments are not crucial in the strictest sense of the word, but they CAN be invaluable tools to people reading code. Comments aren’t intrinsically valuable, however. Their value is only realized when they answer a question held by someone reading the code. Good code comments must serve the needs of the code reader, be that another programmer or your future self.

Share this Article:
  • Digg
  • StumbleUpon
  • del.icio.us
  • Facebook
  • Yahoo! Buzz
  • Twitter
  • Google Bookmarks
  • Print