PBP: 093 Algorithmic Documentation

The Best Practices suggest using a full-line comment before a paragraph of code to explain the algorithm.  This is, in my experience, good advice, and what comments should be used for.

Comments need to describe why you’re doing something, not the obvious parts of what you’re doing.  A comment that says, “Reset the counter” over a line that reads, “$counter = 0” really adds little.  Why is the counter being reset?  I can guess that assigning it to zero resets it, that’s probably clear… why is that happening?  The comment, “Restart the counter for the new record” over that same assignment means so much more.

Yes, describe what the code does if it’s a complex algorithm or not obvious.  That’s a good use of comments, too.  But why you’re doing something in code is really the key part.

The book does note that these should be only one line long, so as not to interrupt code flow.  I think that’s a good general guideline, but sometimes 78 characters just isn’t enough and the words are more important.  This is a place where I think the strict interpretation is a problem and the engineer should use their good judgement, but be trying for brevity when possible.

Leave a Reply