Hacker News Reader

Comment by ams6110 | Hacker News Reader

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.

View on HN

When 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.

It's often said, "A comment is a lie waiting to happen".

And a line of code is bug waiting to happen, especially if no one knows why it is written in the weird way it is.

In theory your unit test would pick that up ;)

It'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.

Bad comments are like bad tests, they're bad. Good comments, like good tests, are a boon for complex software.

A test will at least fail when wrong, a bad comment will just be confusing.

A 'bad test' isn't one that is failing, it's one that doesn't test anything useful, or worse tests something useful but incorrectly

Yes, 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.

Then 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.

Reply on news.ycombinator.com