Comments in the code - useful, senseless, harmful?

Somehow looking through the code of some old modules, I again thought about the role of comments. The question, though trivial and discussed millions of times in books, blogs, articles and forums, but still sometimes hurts me. At the same time, they write about the benefits of comments much more often than about their harm.

Therefore, I will make a few bit of provocative statements, then try to back them up with examples. Let's see what happens. Written applies to both (Java) Doc, and to the usual comments in the code.

So:

')
1. A comment may be helpful, meaningless or harmful.
2. If the comment does not have a clearly visible benefit, then it is most likely harmful.
3. Comments are useless / harmful more often than it seems. No comment is better than useless comment.
4. Before you write a comment - think twice, but maybe not worth it? :)
(5. After you have decided that a comment is still not needed, look three times - and the code is crystal clear? :))

All helpful comments are clear. When:
- it is enough to read 6 lines of comment instead of 80 lines of method code with business logic
- the commentary refers to a implemented little-known algorithm or data structure (for example, “the search for a substring uses the Aho-Coracic algorithm”, a link to Wikipedia or a special site)
- the comment explains why the author uses the wrong approach that the reading code most likely expects to see here (for example, a handwritten SQL query instead of working through the ORM framework, or why regexp is used to search XML, and not XPath)
- the comment gives a short clear example of use (especially if this is some custom Ant task or something like that),

it is almost certainly a useful, and sometimes necessary, comment.

And now let's look at some other common example.
Such a comment is usually created by the default IDE when generating the setter getters for the object field (in turn, if Java had properties and the required synthetic methods were generated by the compiler transparently for the programmer, this problem would not exist either :)).

1. / **
2. * return the enterpriseName
3. * /
4. public String getEnterpriseName () {
5. return enterpriseName;
6. }

The comment is obviously not needed. There is nothing non-trivial in the code, the comment essentially duplicates the code. In addition, the comment here takes up three lines in the code editor. Those. exactly the same as the code itself. Not only is the code itself, in essence, synthetic, + because of the Java Code Conventions it stretches three lines for readability, the comment also eats up the place.
Java and so unimpressive language (in terms of the average amount of useful actions per line of code) compared with, for example, Ruby or Groovy, so why waste screen space for extra comments.

Here, of course, there is a delicate moment. If the code with similar comments is part of the public API of some kind of generic library, and none of the programmers using it almost never looks at its sources, but looks at Javadoc - then this is still normal. But if this code is in a module developed by us, and the source code of this class is viewed more often than its documentation (which is almost always true), then this is IMHO, the case when the rule “any API element should have a comment” should be applied with great care.

The considered example is often further aggravated by the fact that param , return tags are pushed into the comment, which often do not carry useful information, but they eat up the place. For example:

/ **
*
* Some description.
* param paramName1 paramName1
* param paramName2 paramName2
* param paramName3 paramName3
* return the name of user
* /
public String getUserName (String paramName1, int paramName2, int paramName2) {
/ * some simple straight-line code * /
}

(It's funny that often there are such meaningless comments in the code, but in really complicated parts there are few comments :))

And finally, another example.

// Temporary hack the ability to do fine is not supported right now,
// a need to do urgently. On the advice of [senior developer name], hacked like this.
// 04/21/2004, [developer name].

In some examples I partially exaggerate, but the general idea does not change.

Updated:
Upon request in the comments, I give a link to a couple of books that are useful for any programmer to read, so as not to write such comments (and not to make many other mistakes)

Steve McConnell. Perfect code. www.ozon.ru/context/detail/id/5508646
Martin Fowler. Refactoring. Improve existing code. www.ozon.ru/context/detail/id/4952415