I often hear that comments in source code are A Bad Thing. Comments are evil because they don't accurately describe the code they apply to; because the code gets modified and the comment doesn't; because good code is self-documenting and therefore doesn't need comments; and because you need to read the code anyway to understand what it does and so comments just get in the way.
Horseshit.
This is roughly like saying that synchronization is evil, because it's often done incorrectly, because it gets broken when people update the code without fixing the synchronization, and because good code uses constructs like immutability that don't require synchronization.
If we treated comments as being as important as synchronization, they'd live up to their end of the deal just fine. There is nothing inherent in the idea of a comment that renders it impotent. Think of comments as being like error-handling code or synchronization: bulky, hard to write, even harder to test, but crucial to reliability.
I think the real reason so little code is commented is simply that most code is written in short bursts of effort by highly productive individuals, and while they're writing it, they understand their own assumptions well enough to not need the comments themselves, and they're in too much of a hurry to worry about the next fellow. And because this is what new programmers then see all around them, this is how they in turn learn to program.
If we built buildings this way, instead of having architectural drawings, the carpenters would come in after the foundations were poured, look at where the rebar was sticking out, and frame the walls where it looked like they should probably go. The resulting buildings would be ugly, short, and tend to collapse in a few years. Much like software, in fact.
If I were to design a programming language, any uncommented abstract definition (for instance, a method definition in an interface class) would be a compiler error. Yes, people would work around it by putting in useless comments, but it would be a start.
skip to main |
skip to sidebar
It is harder to put a TV back together.
2 comments:
I'm a strong proponent of *useful* comments. You can leave your "getName() gets the name" comments at the door but comments that explain why something happens or reveal intent are as much part of the code as the code itself.
Sure, I agree. For comments in code, the question should be "beyond the code itself, what additional information is needed for someone to understand and maintain this, without having to internalize the entire body of code to which it relates?". For comments on methods and especially on interfaces and abstract method declarations, the question is "what additional information does someone need to know in order to use this correctly, without looking through the implementation?"
So, getName() shouldn't say "get name", it should say "get person's name in Lastname, Firstname format. Will never return null, but may return empty string. Safe to call concurrently."
Of course, putting as much of this stuff as possible into annotation tags is a wonderful idea.
Post a Comment