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.
I developed a “don’t comment” policy for subcontractors. It’s sufficient that they write code that is literate enough for me to understand at least in general.
What I found is that “making” a developer comment most often resulted in them spending hours adding doxygen tags for automatically pretty printing what I could just as easily read in the prototype. “Yes, I can see that the function takes two pointers to int and returns a pointer to a struct of type foobar. NOW TELL ME WHY DAMMIT!”
So I just let it go. Better no comments than crappy comments. As long as the code worked correctly.