I tend not to read code comments and only to write them if something is unusual. As a result, I am terrible at writing a certain style of code comments.
Further, writing code comments for in-house software feels kinda icky to me, because the time seems better spent creating working software. Doing something that I do not believe is useful feels... icky.
That said, I am an adult and am not the source of all truth; so, when a team wants comments, I can suck it up and handle icky feelings.
After receiving some recent training from a very patient member of one of my teams-that-requires-comments, I have come up with the following heuristic for writing the certain kind of comment that this team finds helpful.
- A helpful comment must translate a function signature into English. This answers "what" the function does.
- A helpful comment may also characterize the need it fulfills in upstream code. This answers "why" the function exists.
- A comment is helpful on functions/classes/methods when it isn't possible to read the function/class/method implementation at the point of use (e.g. closed source code or code spread among files).
- When writing a comment, imagine that the reader can see only the Intellisense and cannot see the function signature nor its implementation.
To be clear, this isn't a commenting style that I would advocate. Rather, it is one of the styles of comments that some teams sometimes find useful. Instead, I advocate only using comments to explain why when it is not obvious.
Conversation on Twitter: https://twitter.com/cfe84/status/1136820970176503808