Breaking the comment habit
Why??
Is having comments bad? No, but only after working on a great code base with specs and almost NO comments, I realized how comments in code are bad.
How are comments bad??
Comments require more work to interpret.
Naturally, comments are prose, which when well written, is easy to understand. Even with well written comments, they are a huge distraction in reading code.
When reading through code, I have a certain context in my head and that is how the interpreter will process my code. When a comment comes up, I have to switch context from code, to prose.
Interpreting prose is very different than code. The interpreter just ignores comments so I am on my own. Interpreting comments can be really tough. This context switch is tough for me: load up code, interpret code, unload code, load comment, interpret comment, repeat.
So, the context switch from code to comment is especially taxing to my brain.
Comments fall out of date
Code is enforced by the processor. Comments are enforced by programmers.
Whenever I run into comments where the code does not match, I begin to wonder: am I misinterpreting this code? or am I misinterpreting this comment? or BOTH?
In this case, I rather focus on the code and disregard the comment. At the end, code is being executed, not comments. Any changes I make will be to code, and if I don’t understand the comment, I will just leave it as is. The comment left by another programmer is really a note to them and well, if it is not affecting program operation, why change that?
Solution: specs
Really. Not because I love specs, but working with specs introduced me to using it as a code base’s ‘active documentation’ which is really awesome and easily replace comments in code.
Code separation
Specs live in a different part of the code base from code, so the ‘comments’ part is completely separate from the actual code part. When I want the answer: “how does this work?” I look at the spec section and find the particular description needed with a code sample.
Ideal sample code
Specs always come with code to setup and test a feature. This code helps me develop and test the feature as I go along, but once I am done, it becomes the perfect sample code for me or another programmer to use or revisit the feature.
At the same time, specs are descriptive enough that new programmers can easily understand and also have working example code to learn the code base.
Automated code check
When changes are made to the code, but not to the specs, specs will very quickly find breaking changes because they will fail. At the same time, specs will indicate which specs fail with the change.
When to have comments in code
Are there situations where comments are still needed? Yes! They aren’t the usual situations when specs are in code base.
-
Code which is copy/pasted from another source (ahem stack overflow)
-
Code which has strange behavior but is not covered by the spec (i.e. the specs pass, but the implementation is not very straight forward compared to the rest of the code.)
Situation 1 is when I have to do something unconventional (to me) to solve a problem. Having a reference back to the code source allows me to check if the answer has been improved.
Situation 2 usually comes up when I have encountered issues with the supporting library used and a workaround is needed.
Old [comment] habits are hard to break
Every time I am tempted to leave a comment in my code, a far greater programmer than me always ask:
“Can the code be written so it does not need a comment?”
and almost all the time the answer is a yes. Hence, comments in code are really reserved for external info
So, by writing code without comments, I have discovered:
- I can make my code more expressive and let the code do the talking
- I can get through my code because I’m just in one mode: interpreting code
Conclusion
Having specs really reduces the need for comments in my code, because the specs themselves provide fantastic documentation as they are active documentation for a code base, which separates documentation from code, provide great sample code, and easily find breaking code changes by running the specs.
Comments used sparingly to documented external issues or solutions I got from somewhere else really make a code base shine.
spec more, comment less.
stay specing my friend.