Nachdem Sonar auf einem meiner Projekte ausgeführt wurde, erhalte ich einen Verstoß gegen "nachgestellte Kommentare". Also frage ich mich, ob dies rein auf akzeptierte / empfohlene Code-Layout-Konventionen für Java zurückzuführen ist oder gibt es "mehr dazu"? Was ist der Grund dafür? Wenn ich über etwas C ++ Code schaue (kürzlich Doom Code Review , es gibt Unmengen von Kommentaren.
Aus dem berühmten Buch Code Complete :
Die Kommentare müssen so ausgerichtet sein, dass sie die visuelle Struktur des Codes nicht beeinträchtigen. Wenn Sie sie nicht sauber ausrichten, werden sie Ihren Eintrag so aussehen lassen, als wäre er durch eine Waschmaschine gegangen.
Endzeilenkommentare sind in der Regel schwer zu formatieren. Es braucht Zeit, um sie auszurichten. Eine solche Zeit wird nicht damit verbracht, mehr über den Code zu lernen. Es ist ausschließlich der mühsamen Aufgabe gewidmet, die Leertaste oder Tabulatortaste zu drücken.
Endline-Kommentare sind auch schwer zu pflegen. Wenn der Code in einer Zeile, die einen Endline-Kommentar enthält, größer wird, wird der Kommentar weiter entfernt, und alle anderen Endzeilenkommentare müssen verschoben werden, damit sie übereinstimmen. Stile, die schwer zu pflegen sind, werden nicht gepflegt.
Endline-Kommentare neigen auch dazu, kryptisch zu sein. Die rechte Seite der Linie bietet nicht viel Platz und der Wunsch, den Kommentar auf einer Zeile zu halten, bedeutet, dass der Kommentar kurz sein muss. Die Arbeit geht dann dahin, die Linie so kurz wie möglich anstatt so klar wie möglich zu machen. Der Kommentar endet normalerweise so kryptisch wie möglich.
Ein systemisches Problem mit Endzeilenkommentaren ist, dass es schwierig ist, einen aussagekräftigen Kommentar für eine Codezeile zu schreiben. Die meisten Endline-Kommentare wiederholen nur die Codezeile, was mehr schmerzt als es hilft.
Nachdem wir das gesagt haben, geht es auch um die Wahl des Programmierstils. Ich würde persönlich nachstehende Kommentare vermeiden, da sie das nicht sehr helfen.
Nur weil etwas nachgestellte Kommentare hat, heißt das nicht, dass sie gut sind. Bedenken Sie auch, dass der Code von Doom 3 ~ 10 Jahre alt ist und sich die Kodierungsstile im Laufe der Zeit ändern.
Im Allgemeinen weisen nachgestellte Kommentare darauf hin, dass eine Codezeile nicht eigenständig stehen kann. Und im Allgemeinen ist das ein Code-Geruch, weil eine einzelne Codezeile ziemlich transparent sein sollte.
Wenn ich einige der Quellen durchschaue, sehe ich eigentlich nicht viele anhängige Kommentare, obwohl ich viele Methoden sehe, die zu lang sind, und viele Kommentare mitten in den Funktionen .
Diese geben oft an, dass der folgende Code eine eigene Methode verdient.
Ich würde argumentieren, dass ja, da ist mehr dran, und das "mehr" ist Kommunikation und Klarheit.
Trailing-Kommentare sind per se nicht schlecht. Sie sollten Ihren Code jedoch so klar wie möglich schreiben, damit Sie Ihren Code nicht zeilenweise mit Kommentaren erklären müssen. Das ist der Grund, warum manche Leute die Kommentare in absteigenden Code als einen Hinweis betrachten, dass der Code nicht verständlich genug ist.
Siehe auch den Java Style Guide für weitere Informationen.
Tags und Links java sonarqube code-comments