[bdibs]

My comment was directed to the OP's question of comment:code ratio in general, not in this exact circumstance.

Additionally, in no way am I advocating for no comments, that's obviously not possible (like your example). Comments are useful, even necessary, for code that might have an otherwise confusing logic to them.

I've seen plenty of code with documentation for a method with nothing more than:

  /**
   * Bills the user
   *
   * @param user The user to bill
  */
  public void billUser(User user) {
    //
  }

In my opinion, that comment is completely redundant, and I think it's driven by the idea that we should comment EVERYTHING.

[The6P4C]

Though there should definitely be documentation here. What happens if `user` is null? What if the user doesn't have enough balance for the transaction to complete? What if the transaction fails?

I see this as someone trying to fool a linter that demands they have documentation. I think it's better to say "comment everything" because it puts documentation as a first-class consideration rather than an afterthought.

[mannykannot]

If it is a general principle, then would one not expect it to apply in this case? More importantly, this is not a corner case; situations where there are specific conventions and protocols that have to be handled consistently in various cases are extremely common in software. It is also not uncommon to see optimized code that is much easier to understand when it is explained as a modification of a simpler implementation.

With regard to the sample, then if that is your experience, I cannot deny it, but, irritating as it may be, it seems fairly harmless. It appears to date from a time when it was thought that extremely prescriptive coding style standards was the way to fix programming - an even less realistic belief than the idea that code can be entirely self-documenting.

[tuananh]

no, in case like this, it's mostly for documentation generation. though you may find it useless.

[tengbretson]

Worse than useless. It harms your ability to take in multiple things at once on your screen.