We’d been having a discussion about code commenting on our CRineta.org discussion group. I’d been asserting that we need to comment “WHY” a piece of code is in place more so that “WHAT” it does. Chris requested for me to show what “WHY” comments would look like on a specific piece of code. I thought about it for awhile but soon was distracted by real life. I continued to think about it and realized why I was unable to easily come up with a “WHY” comment for it. The reason is exactly the reason I’ve been asserting the need to write the “WHY” comments along with the code … because by the time I read this piece of code (the one Chris asked me to demonstrate on) the “WHY” information wasn’t available to me. I could have made something up, but in truth, the person who wrote the block of code is the one who knew why it was written, its purpose for being.
While doing a code review today, I found a good example. Here’s the original code as I reviewed it – with the comments from a guy who generally does a good job of commenting his code.
// Retrieve the statement info so we have it.
StatementInfoCache.Instance.GetStatementInfo(statementID);
// Start the delete statement job on the server.
Guid jobID = Guid.NewGuid();
StatementUsageResponse response =
StatementListModelHelper.DeleteStatement(
this, statementID, jobID);
if (response.RequestResult == StatementUsageResponseResult.Successful)
JobManager.JobManager.Instance.AddJob(jobID);
return response;
Focus on the first line. I asked about it during the code review. I asked WHY do you have to get the statement info? Knowing what I did at the time, I already knew what “so we have it” meant. But why did we need it, and would we remember why we had to have it one month from now? How about 6 months from now?
So the developer revised the comment as follows:
Version 2:
// Retrieve the statement info because we can’t after the delete.
Ah – true. That is a reason we have to get it now, because we are doing a DeleteStatement operation and the Statement Info won’t be available after the delete. But still I asked – WHY do you need to have the statement info? The line isn’t just there for our health? So he modified the comment again with a bit more prompting.
Version 3:
// Retrieve the statement info because we can’t after the delete.
// This is so the notification box and job monitor can show the statement description.
Wonderful. Now I know WHY we are getting the Statement Info AND I know WHY we are getting it now.
This is the kind of information that one would have to do significant searching for at a later date when trying to understand the code, which was originally:
// Retrieve the statement info so we have it.
StatementInfoCache.Instance.GetStatementInfo(statementID);
I’ve read others opinions on code commenting such as Jeffery Palermo’s. I think that many peoples perspective on commenting code, especially those that say that code should be written to be self documenting, aren’t necessarily wrong, they are just focused on the wrong nature of how comments should be applied.
So I say, “Tell me WHY“.
