Forcing functions that are better than comments
A recent thread at work discussed the value (or otherwise) of comments in code. I think comments on anything owned and used by a small team are usually a code smell.
One of the excuses offered for comments was that if you wrote e.g. JavaDoc for some code, then that forces you to think about the details of the code’s behavior and the way that it presents itself to clients; and that such thinking catches edge cases, and prompts redesign all the way from minor naming tweaks through to major simplifications.
I agree completely that the forcing function of explicitly expressing one’s intent has that value. And it’s a really significant value. But tests do it better than comments without any of the “eventual inconsistency” downsides.
This is old news. But then I noticed a pattern I thought worth posting:
One genuine usefulness of comments can be in providing the “why” instead of the “what”: to give the motivation for behavior rather than simply a description. And making motivation explicit is as valuable to a developer as making descriptions explicit is. It analogously exposes gaps in thinking, and prompts re-aiming toward equally valuable goals that are easier to hit.
Tests are only good for expressing descriptions, not motivations. So here they can’t play the same role of a superior substitute forcing function to comments. You know what can though? Talking with your pair.
