I don't really agree. Which is to say, good comments are helpful, but they are a flashlight in a dark room. If there's lots of furniture and clutter in the room, you still might trip over something.

How many times in your codebase have you seen a comment like:

    // This exists because that dumb thing happened, 
    // and during the migration from Y to Z we had to 
    // support these two systems simultaneously. This
    // component mediates between the two . . .

And someone had added some common logic into the mediator, then someone else had hooked into that, and now there's a snarl.

The most important thing is that the system be as simple as it can while still performing its intended functions. We have all made a first cut at something that ended up being three times as verbose or complicated as our second. You want a system made out of pieces of the second kind. That's even more important than comments.

I can definitely understand the desire to reduce lines of code, because it's often a good proxy for understanding how complicated a system is. Not always, but most of the time, something a quarter as long that does the same job is doing it a simpler way.

That's an easy question: it almost never happens. The most frequent occurrence (by far) is that there are no comments at all, just a wall of indecipherable code. Even an old comment describing intent and usage is better than no comments at all.

In your example, even if that comment is outdated, it's still incredibly useful. It tells you, in under 5 seconds, the original intent of a piece of code, and how it was supposed to fit into the entire system. That's something you'll never get without a comprehensive understanding of the project, which takes far more than 5 seconds of reading. The real problem here is not that there is a comment -- the problem is that a bad coder fucked up by not updating the comment. There's no excuse.

That all of the commenters below will spend paragraphs explaining how they shouldn't have to document their code with the occasional descriptive comment is an amazing testament to the overwhelming power of human laziness and self-delusion.

My point is not that this comment is unhelpful. My point is that it would be better if the reason for this comment's existence were eliminated. I.e. that the removal of unnecessary complication in the system is an even more laudable goal than commenting well.

Obviously, both will have a part in any well written an maintained system. But the person I'm responding to held good comments up as the most important aspect of system maintainability, and that is simply not the case.

You were responding to me, and no, that's not what I meant. ;-)

I'm not saying that comments are the "most important" aspect of system maintainability, but that they're one of a few things that are all of top importance.

Obviously, if you write spaghetti code, your system won't be maintainable, no matter how many comments you write. But that's a false dichotomy: you need to write good code and you need to write good comments. Neglecting either one leads to unmaintainable systems.

I try to avoid having to write implementation comments. If I find I need comments, then it's a warning that I may be too clever by half. I prefer a description of what the function is supposed to do rather than how it accomplishes it's goal.

Even so, there are some times when I need to write some mentally dense code to accomplish several competing goals. It is then where I explain what's going on and why the code was built that way.

I have to wonder what a good comment gives that a good set of tests wouldn't also provide, plus all of the extra benefits that come from having automated tests? It seems like they both exist to solve the same problem (to explain intent, show usage, etc.), with just one being more formal about it.

Sometimes, code is hard to read due to being optimized. In that case, it's often easier to read a short comment than having to parse the code.

  // p.xyz += f.xyz * timeStep
  __m128 ts = _mm_load1_ps(&timeStep);
  __m128 x, y, z;
  __m128 fx, fy, fz;
  for(int i = 0; i < NUM_PARTICLES; i+=4) {
      x = _mm_load_ps(px + i);
      y = _mm_load_ps(py + i);
      z = _mm_load_ps(pz + i);
      fx = _mm_load_ps(pfx + i);
      fy = _mm_load_ps(pfy + i);
      fz = _mm_load_ps(pfz + i);
      x = _mm_add_ps(_mm_mul_ps(fx, ts), x);
      y = _mm_add_ps(_mm_mul_ps(fy, ts), y);
      z = _mm_add_ps(_mm_mul_ps(fz, ts), z);
      _mm_store_ps(px + i, x);
      _mm_store_ps(py + i, y);
      _mm_store_ps(pz + i, z);
  }

Sometimes, it's because you're doing something that looks surprising, but is there for some reason, so that the next time someone looks at that code, they know why something is done in that fashion.

  val loginForm = Form(
    tuple(
      "email" -> text,
      "password" -> text,
      "rememberMe" -> optional(text)  // jfim: HACK For some reason, having this as boolean causes a None.get in Play 2.1.0
    )
  )

Comments should be there to explain why the code does something or what it does in a more readable fashion(because it's faster to read plain English than code), neither of which can be covered by tests.

I actually agree with you completely, but such cases should be rare, and doesn't seem to be what the parent was talking about.

That's fine if you have a team disciplined enough to write useful comments and keep them up to date. Personally I haven't seen that very often.

Just to add to siblings, I'd propose a rule of thumb of at most 2 sentences per "page" of code, where a page is about as much code is on your screen at a readable size.

It's a rule of thumb, and snark will put you over that easily, but IME, it can suggest you're getting overzealous about commenting when you've got more than that.