Code Review #8: When to comment

The last ? in a series of posts about commenting. See “the why”. See “not commenting is career threatening”. And the comment that started this off!

This post should have really been the second one I wrote. The first post was about who a developer needs to keep happy – the client or the manager.

But commenting everything is both hard, excessive, and wasteful of time. In “the why” post, I cover what should be in the comments – implicitly I was limiting comments to just the places where knowing “the why” is important.

However, still the question is “when” should a developer comment?

Here is my rule of thumb:

  • Any developer had to spend time figuring out what the code did. Refactor it and if still not clear comment the code with questions and assumptions. (Just in case the refactoring introduced a bug or caused an existing bug to appear.)
  • Another developer asks the implementing developer (or the current “owner”/responsible developer) about the code, interfaces, package. The developer asking the question copy the explanation into the code, cleaning up the chat log/email response and adding further edits and explanation as needed.
  • The code is not going to have further development for a while. Comment the code enough so that when development is resumed, the restart is faster.
  • The code is being handed off from one developer to another.
  • Key interfaces that are used by multiple groups.

And managers give developers time to wrap up and add these comments.

Conversely, what is not worth commenting:

  • Code that is actively, daily, being changed rearchitected. Every developer already knows what the comments would say and the structure is changing fast enough that the comments would become outdated.
  • Code that does not impact data integrity and end-user experience in a horrid way.
  • Utility classes/ methods.
This entry was posted in code review, management. Bookmark the permalink.

1 Response to Code Review #8: When to comment

Leave a Reply

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