[mannykannot]

Well, let's consider an example from this very code:

  // The binding is two-step process. PV.Spec.ClaimRef is modified first and
  // PVC.Spec.VolumeName second. At any point of this transaction, the PV or PVC
  // can be modified by user or other controller or completely deleted. Also,
  // two (or more) controllers may try to bind different volumes to different
  // claims at the same time. The controller must recover from any conflicts
  // that may arise from these conditions.

How would you rewrite the code so that this information was explicit in the code alone, and as obvious as when it is stated in these comments? Note that simply being able to handle any conflicts that may arise from these conditions is not necessarily the same as saying that they can occur and must be handled, as any particular implementation is invariably an over-specification.

As for redundant comments explaining the obvious, that seems to be something of a straw man, at least in my experience - personally, I have very rarely seen such code. The person who is not motivated to write useful comments apparently prefers to write no comments rather than useless ones.

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