[julsonl]

The issue I have with commenting is some people enforce it for the sake of having comments in place, which would most of the time describe the "what" and the "how" of the code, rather than the "why", which in my opinion, where most of the value lies. In Java, the usual offenders would be the getter and setters in POJOs, like:

  * Returns the name
  * @return the name
  */
 public String getName();

[flatline3]

Comments like that exist simply to appease documentation tools that can't derive those comments automatically.

The net gain is that you get nice API documentation. The downside is that you have a verbose and obvious comment in the source.

[slurgfest]

Aren't such comments usually autogenerated by the IDE or such tools?