Sonar, java and follow-up comment violation

Question

After starting Sonar in one of my projects, I get a violation for comments with comments. So, interestingly, is this purely related to the accepted / recommended code layout conventions for Java, or is there still “this”? What are the reasons for this? When I look at some C ++ code (a recent review of Doom code , there are tons (or full bindings) of trailing comments.

Answer 1

From the famous Code Complete book:

• Comments should be aligned so that they do not interfere with the visual structure of the code. If you don't align them neatly, they will make your list look like a washing machine.

• Endline comments are usually difficult to format. It takes time to equalize time. Such time is not wasted learning more about the code; it focuses on the extremely tedious task of pressing the space bar or tab key.

• Endline comments are also hard to maintain. If the code on any line containing a comment at the end of the line grows, it deletes the comment further, and all other comments at the end of the line must be knocked out to match. Styles that are difficult to maintain are not supported.

• Endline comments are also critical. The right side of the line does not offer much space, and the desire to leave a comment on one line means that the comment should be short. Then work proceeds to make the line as short as possible, and not as clear as possible. Commentary usually ends as mysterious as possible.

• The system problem with comments at the end of the article is that it is difficult to write a meaningful comment for one line of code. Most comments at the end of the line simply repeat the line of code, which hurts more than it helps.

Having said that, this also applies to one choice of coding style. I would personally avoid comments, as they do not help much.

Answer 2

Just because something has final comments doesn’t mean that they are good. Also keep in mind that Doom 3 code is ~ 10 years old, and coding styles change over time.

In general, trailing comments indicate that a line of code cannot stand on its own. And, in general, that smell of code, because one line of code should be transparent enough.

Looking through some source, in fact, I do not see a ton of comments, although I see many methods that are too long and many comments in the middle of functions.

It is often pointed out that the following code deserves its own method.

I would say that yes, there is more, and “more” is communication and clarity.

Answer 3

Tracking comments is nothing bad in itself. However, you should write your code as clearly as possible so that you do not have to explain your code in a line using comments. This is why some people consider the final comments of the codes a hint that the code is not clear enough.

See the Java Style Guide for more information on this.