Codestyle; Javadoc vor oder nach der Annotation setzen?

183

Ich weiß, dass dies nicht das wichtigste Problem ist, aber ich habe gerade festgestellt, dass ich den Javadoc-Kommentarblock vor oder nach der Anmerkung einfügen kann. Was möchten wir als Codierungsstandard übernehmen?

/**
 * This is a javadoc comment before the annotation 
 */
@Component
public class MyClass {

    @Autowired
    /**
     * This is a javadoc comment after the annotation
     */
    private MyOtherClass other;
}
java coding-style annotations javadoc code-documentation Paul McKenzie
quelle

Antworten:

191

Vor der Annotation, da die Annotation Code ist, der zur Klasse "gehört". Siehe Beispiele mit javadoc in der offiziellen Dokumentation.

Hier ist ein zufälliges Beispiel, das ich auf einer anderen offiziellen Java-Seite gefunden habe :

/**
 * Delete multiple items from the list.
 *
 * @deprecated  Not for public use.
 *    This method is expected to be retained only as a package
 *    private method.  Replaced by
 *    {@link #remove(int)} and {@link #removeAll()}
 */
@Deprecated public synchronized void delItems(int start, int end) {
    ...
}
Peter Jaric
quelle
8
Auch hier von Interesse - die Anmerkung befindet sich in derselben Zeile wie die anderen Qualifikationsmerkmale für die Methode. Ich habe das noch nie zuvor gesehen, aber es scheint nahezulegen, dass Anmerkungen ähnlich wie andere Qualifikationsmerkmale für eine Methode behandelt werden sollten, und als solche sollte der Javadoc definitiv davor stehen.
ArtOfWarfare
8
Wenn Sie dieselben Anmerkungen wie Jackson verwenden, kann es schnell außer Kontrolle geraten, dieselben Anmerkungen in dieselbe Zeile zu setzen. Ich habe jede Anmerkung in eine eigene Zeile eingefügt.
WW.
17

Ich stimme den bereits gegebenen Antworten zu.

Anmerkungen sind Teil des Codes, während Javadoc Teil der Dokumentation ist (daher der Name).

Für mich ist es also vernünftig, die Codeteile zusammenzuhalten.

perdian
quelle
11

Auf die Lesbarkeit kommt es an. Meiner Meinung nach ist der Code mit den Anmerkungen direkt über der Methode / dem Feld besser lesbar.

Robby Pond
quelle
11

Abgesehen vom Codierungsstandard scheint das Javadoc-Tool die Javadoc-Kommentare nicht zu verarbeiten, wenn sie nach den Anmerkungen platziert werden. Funktioniert sonst gut.

Shadrik
quelle
0

Ich stimme all dem zu. Für andere kann es hilfreich sein, dass die Codestilvorlagen von IntelliJ (Idea) bei Verwendung des RestEasy-Stils sowohl falsch positiv (wenn @throws korrekt angegeben ist, warnt es) als auch falsch negativ (wenn @throws nicht angegeben ist, aber sein sollte) fehlschlagen Anmerkungen. Ich setze meine Javadocs über alles andere, dann Anmerkungen, dann Code.

Den Fehlerbericht finden Sie hier: https://youtrack.jetbrains.com/issue/IDEA-220520

Max P Magee
quelle