Codestil; javadoc vor oder nach annotation setzen?

Lesezeit: 2 Minuten

Benutzer-Avatar
Paul McKenzie

Ich weiß, dass dies nicht das wichtigste Problem ist, aber ich habe gerade festgestellt, dass ich den Javadoc-Kommentarblock vor oder nach der Anmerkung platzieren kann. Was würden wir als Kodierungsstandard übernehmen wollen?

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

    @Autowired
    /**
     * This is a javadoc comment after the annotation
     */
    private MyOtherClass other;
}

Benutzer-Avatar
Peter Jarich

Vor der Anmerkung, da die Anmerkung Code ist, der zur Klasse “gehört”. Sehen Beispiele mit javadoc in der offiziellen Dokumentation.

Hier ist ein zufälliges Beispiel, das ich gefunden habe eine weitere offizielle Java-Seite:

/**
 * 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) {
    ...
}

  • Auch hier von Interesse – die Anmerkung befindet sich in derselben Zeile wie die anderen Qualifizierer für die Methode. Ich habe das noch nie zuvor gesehen, aber es scheint darauf hinzudeuten, dass Anmerkungen ähnlich wie andere Qualifizierer für eine Methode behandelt werden sollten, und als solche sollte das Javadoc definitiv davor stehen.

    – ArtOfWarfare

    6. November 2013 um 18:42 Uhr

  • Das Einfügen derselben Anmerkungen in dieselbe Zeile kann schnell außer Kontrolle geraten, wenn Sie etwas Anmerkungslastiges wie Jackson verwenden. Ich setze jede Anmerkung in eine eigene Zeile.

    – WW.

    10. April 2015 um 2:43 Uhr

Ich schließe mich den bereits gegebenen Antworten an.

Anmerkungen sind Teil der Code während javadoc Teil von ist Dokumentation (daher der Name).

Daher erscheint es mir sinnvoll, die Codeteile zusammenzuhalten.

Benutzer-Avatar
Schadrik

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

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

Ich stimme allem oben Genannten zu. Es kann für andere hilfreich sein, dass die Codestilvorlagen von IntelliJ (Idea) bei Verwendung des RestEasy-Stils sowohl falsch positiv (wenn @throws richtig angegeben ist, wird gewarnt) als auch falsch negativ (wenn @throws nicht angegeben ist, aber sein sollte) fehlschlagen Anmerkungen. Ich habe meine Javadocs über alles andere gestellt, dann Anmerkungen, dann Code.

Siehe den Fehlerbericht hier:
https://youtrack.jetbrains.com/issue/IDEA-220520

1353980cookie-checkCodestil; javadoc vor oder nach annotation setzen?

This website is using cookies to improve the user-friendliness. You agree by using the website further.

Privacy policy