6 ms·
11. Know when to break any of the first 10 rules. 12. Never listen to anybody who tells you "You shouldn't need comments if your code is clear enough to read."
by jlg23 11y ago
11. Know when to break any of the first 10 rules.
12. Never listen to anybody who tells you "You shouldn't need comments if your code is clear enough to read." - the next one reading your code (probably you, 10 years later) will love you for documenting the WHY just as much as s/he'll hate you for having to rely on documentation that explains the WHAT.
- eCa 11y agoI agree, but: "reduces the need for comments" != "shouldn't need comments"
- piess 11y agoWell said
- ap22213 11y agoDon't they teach kids how to read code these days?
- MaybiusStrip 11y agoI like how Robert C. Martin puts it: before you write a comment, ask yourself whether you can write the code in a way that makes the comment unnecessary. If you cannot, then it is better to leave the comment than none at all.
- mannykannot 11y agoFair enough, so long as you understand that programming languages are not expressive enough, in general, to clearly explain purpose and rationale. In these matters, providing a hint through identifier naming is not an adequate substitute for a clear explanation in a human language.
- roddux 11y agoAs an aside, clearly written code does a pretty good job of explaining what it does, but not why. Sometimes there will have been reasons for avoiding a particular method, which isn't made obvious by the code itself.
- mark-r 11y agoI was going to say that, glad someone beat me to it. No matter how clear your code is, it can't explain the WHY.
- imron 11y agoHowever 10 years later, it is also likely you'll be reading the comments for the explanation and realise that what the comments say is different from what the code does (because over the span of 10 years the code was updated but not the comments) and that's just as confusing. If the code is written with meaningful variable and function names, and functions no larger than a screen, then lack of comments isn't really a problem.
- yoklov 11y agoYep, and often the code that breaks what the comment says is far away. Too easy to change something that subtly invalidates a comment in some other module. Especially if you didn't write that module.
- mannykannot 11y agoIt is also possible that your change subtly invalidates the semantics implied by the identifiers used in some other module. In either case, there is a nontrivial possibility that you have introduced a bug (and quite possibly a subtle one).
- mannykannot 11y agoVariable and function names can be just as misleading as comments. I am not aware of any language which guarantees the semantics implied by your choice of identifiers.
- mywittyname 11y ago> will love you for documenting the WHY just as much as s/he'll hate you for having to rely on documentation that explains the WHAT. I've saved myself so many times with this. External services are bad about having odd-ball edge-case errors that require a little funny business on your end in order to keep operational. So there are often little code snippets that look like their bugs, but are actually necessary to prevent regressions. Without a comment as to why the code is there, some boy scout is going to "fix" it (and the now failing unit test) and introduce a regression.
- joshka 11y agoAnyone that breaks code and then doesn't investigate why a unit test exists is not a boy scout, but a vandal.