3 ms·
The thing about comments is that they don't get maintained. So the comments end up diverging from the implementation. The tests all pass even if the comments
by ams6110 14y ago
The thing about comments is that they don't get maintained. So the comments end up diverging from the implementation. The tests all pass even if the comments are wrong, so nobody cares unless you are particularly diligent about code reviews of EVERY commit.
Also this should go without saying but I still see comments like this:
// loop over the collection
for (var foo in bar) {
...
}
which are not helpful and just clutter the code.
- robmcm 14y agoIt's often said, "A comment is a lie waiting to happen".
- InclinedPlane 14y agoIt's a huge anti-pattern, because then people train themselves to think that slamming out a lot of trivial and redundant comments is a good use of their time. Worse, then they get used to writing lots of trivial comments and the really important more complex or subtle comments go unwritten.
- wulczer 14y agoBad comments are like bad tests, they're bad. Good comments, like good tests, are a boon for complex software.
- seanmcdirmid 14y agoA test will at least fail when wrong, a bad comment will just be confusing.
- garethadams 14y agoA 'bad test' isn't one that is failing, it's one that doesn't test anything useful, or worse tests something useful but incorrectly
- wulczer 14y agoYes, thank you, sorry for too big of a mental shortcut. By bad tests I mean trivial tests (much like trivial comments that just state the obvious), or ones that work on an assumption that need not be generally true and thus changes of the code that are correct from a logic standpoint might still make them fail.
- seanmcdirmid 14y agoThen such bad tests don't mislead, they are just a waste of energy and provide no assurance. At least if the test fails and the code is good, you will know to fix the test. Nothing like that with comments written in human natural language.
- kaolinite 14y agoWhen I write code, the first thing I do is write out the code inside comments - including stuff like "Loop over the collection:". Once I've written the comments, I start filling in the code. I find that whilst this generates "unhelpful" comments, it leads to much cleaner and well designed code. There's another advantage too. If your IDE or text editor changes the colour of comments, as it should, to a colour different to that of the code, then you can ignore all the code and simply read the comments. I find this makes skimming through code much faster. Granted, this won't work in all situations. If you can't trust your colleagues to keep the comments updated (and if you don't review commits), then this is going to cause problems - however if you're writing for yourself or with a small group of people you trust, I strongly recommend giving it a go.