Code Review #7 – Comment the “why” not the “what”

[This post continues the response to Mike.]

Clean “good” code is good but not enough. Code needs comments — but the right kind of comments.

“What” comments are useless and the most quickly out-dated. An example of a what comment is: “add the suffix path to the end”.

However, the post “Thoughts on how to evaluate code” was very specific referring to “why” comments.

Code no matter how “clean” can not self-document. Excellent comments are “why” comments. “Why” comments talk about :

  1. the assumptions / program state the code is expecting. (For example, the user is logged in, premium membership, or admin privileges )
  2. other code affected if this code is changed (For example, setting up a language default for the session, a default that another piece of code is expecting to be set.)
  3. if something is being done in a non-standard way – why it is being done that way (for example, iterating through a loop from high index to low-index rather than the standard low to high)
  4. should the code in question be used as an example pattern of how to do similar operations elsewhere in the code – or should a developer instead use a different pattern elsewhere.
  5. list the assumptions or conditions that require this implementation (with timestamp) so that it is easy to spot code that is present to handle conditions that no longer exist. For example, a comment like this: “12/20/2007 – yahoo’s open id implementation is using the openid 0.8-proposedspec.” Its pretty likely that the the spec has changed as has yahoo’s implementation. This wasn’t a HACK but knowing that reason behind the code is invaluable.
  6. Future work planned.
  7. Alternative solutions that were rejected (and why).
  8. Performance considerations – this code might be special because it executes millions of times a second. So there is good reasons for some “ugliness”.
  9. Update: Why the code was NOT done in a certain way.maybe the usual way to do a certain operation has resulted in a bug (reference the bug number in the comment! )
  10. Update: You, as a developer, are confused by the code. Document your confusion! You may have just discovered a bug.
  11. Update: Document other code looks related for a possible later refactoring.
  12. Update: Document code that should be removed ( Java’s @Deprecated is very useful in this regards because IDEs can mark references to the deprecated code )

The developer, at the moment they are writing the code, must be able to explain why they are writing the code a certain way. It is a red flag to any developer if they cannot explain the why. They should double-check to make sure they understand the requirements. Chances are they don’t and they are doing the wrong thing.

I started requiring developers to clearly document the “why” in their code. I discovered developers that were doing things “wrong” because they were unaware of the correct solution. I discovered that I was not as clear in conveying the requirements as I really thought. Without the developer’s “why” comment, it is easy to get frustrated with developers for the wrong reasons.

Parting thought

Why should the developers that come after the original developer have to spend any time ( and money! ) figuring out the previous work?

You may be the next developer.

This entry was posted in code review, management, technical. Bookmark the permalink.

7 Responses to Code Review #7 – Comment the “why” not the “what”

  1. Pingback: Just wondering…. » Blog Archive » When to comment

  2. Pingback: Code review #10: No emailed code questions | Just wondering….

Leave a Reply

Your email address will not be published. Required fields are marked *