At some point I took to heart admonitions to not write comments that simply repeat what the code clearly says. A discussion with a co-worker, Achint, not too long ago made me realize that this is bad advice. And I should have know better.
“Don’t repeat yourself.”
—Dave Thomas & Andy Hunt
In (human) language, redundancy is a feature.
—me
In programming, the DRY principle is rightly lauded. Not just for code itself but for every bit of information in a software system.
But it’s the opposite for human language. In this case, redundancy makes things clearer. Saying something in both English and code will help the human reader (including your future self) understand the code better and faster.
Certainly, there are situations in which code is clear enough on its own, but—in general—it’s probably better to err on the side of more comments. I’ve seldom seen (or written) code that had too many comments.
But I have sometimes seen code with too many comments. The most common is doxygen boiler plate without any useful content. The other is some of the code written in “literate coding” style.
1 comment:
I think a useful approach is to avoid (like the plague) comments focused on WHAT the code does. Comments on WHY (and to a lesser extent HOW) will often be useful. However, those frequently fit better "at the top" of some unit of abstraction. Inline comments often have a WHAT flavor and I think DRY should apply. Redundancy breeds inconsistency, at least in "living" documents. Of any kind mind you, not just programs. Just my $0.02 of course.
Post a Comment