Wie schreibe ich Javadoc von Eigenschaften?

93

Ich habe oft ein Dilemma, wenn ich Javadoc für Eigenschaften / Mitglieder einer "einfachen" POJO-Klasse schreibe, die nur Eigenschaften und Getter und Setter enthält (DTO-Stil) ....

1) Schreiben Sie Javadoc für die Eigenschaft
oder ...
2) Schreiben Sie Javadoc für den Getter

Wenn ich Javadoc für die Eigenschaft schreibe, kann meine IDE (Eclipse) dies (natürlich) nicht anzeigen, wenn ich später über die Code-Vervollständigung auf das POJO zugreife. Und es gibt kein Standard-Javadoc-Tag, mit dem ich das Getter-Javadoc mit der eigentlichen Eigenschaft Javadoc verknüpfen kann.

Ein Beispiel:

public class SomeDomainClass {

  /**
   * The name of bla bla bla
   */
  private String name;

  /**
   * @return INSERT SOME SMART JAVADOC TAG LINKING TO name's javadoc
   */
  public String getName() {  
    return name;  
  }  

Grundsätzlich wäre es also interessant zu hören, wie andere vorgehen, damit Ihre Eclipse-IDE die Beschreibung der Javadoc-Eigenschaften für Ihre Getter anzeigt - ohne den Javadoc-Kommentar duplizieren zu müssen.

Ab sofort denke ich darüber nach, in meiner Praxis nur die Getter und nicht die Eigenschaften zu dokumentieren. Aber es scheint nicht die beste Lösung zu sein ...


quelle
1
Interessante Diskussion dazu hier: stackoverflow.com/questions/1028967/… . Die akzeptierte Antwort bezieht sich auf Ihre Fragen zu Eclipse / javadoc.
b.roth
Scheint, als hätten sie mit dem Schluss gemacht, was ich in Betracht gezogen habe ... schreibe Javadoc nur in die Getter.
Ich habe einen Weg gefunden, dies mit Anmerkungen zu tun, die in Eclipse funktionieren und sogar zur Laufzeit gesammelt werden können. Wäre das eine Option?
Wassermann Power
private Mitglieder brauchen Javadoc?
Cherit
Der Name von bla bla bla: bestes Beispiel
Rodrigo Espinoza

Antworten:

75

Sie können private Mitglieder beim Generieren von Javadocs (mit -private) einbeziehen und dann mit @link auf diese Feldeigenschaft verlinken.

public class SomeDomainClass {
    /**
     * The name of bla bla bla
     */
    private String name;

    /**
     * {@link SomeDomainClass#name}
     */
    public String getName() {
        return name;
    }
}

Wenn Sie das Javadoc nicht für alle privaten Mitglieder generieren möchten, können Sie alternativ eine Konvention festlegen, um alle Getter zu dokumentieren und @link für Setter zu verwenden.

public class SomeDomainClass {
    private String name;

    /**
     * The name of bla bla bla
     */
    public String getName() {
        return name;
    }

    /**
     * {@link SomeDomainClass#getName}
     */
    public void setName(String name) {
        this.name = name;
    }
}
Chandra Sekar
quelle
2
Ich habe sowohl mit @ link- als auch mit @ see-Tags experimentiert. Aber ... zumindest zeigt Eclipse dies nicht richtig an. Eclipse zeigt den Link als ... (Trommelwirbel) .... Link an, auf den man klicken muss, um den Inhalt zu sehen. Ich möchte in der Lage sein, die Code-Vervollständigung zu aktivieren (oder mit der Maus darüber), um das Javadoc für eine Eigenschaft zu erhalten, wenn ich tatsächlich einen Getter durchsuche ...
13
@Kenny - Modellieren Sie Ihre JavaDoc-Praktiken nicht anhand der Benutzerfreundlichkeit von Pcl of Eclipse. Führen Sie dies aus dem POV aus, um die richtige (oder ausreichend gute) JavaDoc-Ausgabe zu erhalten. IDEs ändern sich, und was heute möglicherweise mangelhaft ist, wird möglicherweise morgen
behoben
1
@luis @linkbedeutet einen Link, auf den geklickt werden muss, um den aktuellen Javadoc anzuzeigen . Es ist kein Eclipse-Usability-Problem, sondern die falsche Lösung für die Bereitstellung einfach zu verwendender Javadocs.
NateS
4

Lombok ist eine sehr praktische Bibliothek für solche Aufgaben.

@Getter
@Setter
public class Example {
    /**
     * The account identifier (i.e. phone number, user name or email) to be identified for the account you're
     * requesting the name for
     */
    private String name;
}

Das ist alles was du brauchst! Die @GetterAnnotation erstellt eine Getter-Methode für jedes private Feld und hängt das Javadoc daran an.

PS : Die Bibliothek hat viele coole Funktionen, die Sie vielleicht auschecken möchten

Amanuel Nega
quelle
3

Ich mache beides, unterstützt von Eclipse's Autocomplete.

Zuerst dokumentiere ich die Eigenschaft:

/**
 * The {@link String} instance representing something.
 */
private String someString;

Dann kopiere ich dies und füge es in den Getter ein:

/**
 * The {@link String} instance representing something.
 */
public String getSomeString() {
    return someString;
}

Bei Eclipse haben @ return-Anweisungen eine automatische Vervollständigung. Daher füge ich das Wort Gets hinzu, schreibe das "t" in Kleinbuchstaben und kopiere den Satz mit dem Kleinbuchstaben "t". Ich benutze dann @return (mit Eclipse Autocomplete), füge den Satz ein und schreibe dann das T in der Rückgabe in Großbuchstaben. Es sieht dann so aus:

/**
 * Gets the {@link String} instance representing something.
 * @return The {@link String} instance representing something.
 */
public String getSomeString() {
    return someString;
}

Schließlich kopiere ich diese Dokumentation in den Setter:

/**
 * Gets the {@link String} instance representing something.
 * @return The {@link String} instance representing something.
 */
public void setSomeString(String someString) {
    this.someString = someString;
}

Dann ändere ich es und mit Eclipse Autocomplete können Sie nicht nur das @ param-Tag, sondern auch den Namen des Parameters erhalten:

/**
 * Sets the {@link String} instance representing something.
 * @param someString The {@link String} instance representing something.
 */
public void setSomeString(String someString) {
    this.someString = someString;
}

Dann bin ich fertig. Meiner Meinung nach macht es dieses Templating auf lange Sicht viel einfacher, sich nicht nur durch Wiederholung daran zu erinnern, was die Eigenschaft bedeutet, sondern es macht es auch einfacher, dem Getter und Setter zusätzliche Kommentare hinzuzufügen, wenn Sie eine Seite hinzufügen möchten Effekte (z. B. keine Null-Eigenschaften zulassen, Zeichenfolgen in Großbuchstaben umwandeln usw.). Ich habe untersucht, wie ich ein Eclipse-Plugin für diesen Zweck erstellen kann, aber ich konnte keinen geeigneten Erweiterungspunkt für das JDT finden, also habe ich aufgegeben.

Beachten Sie, dass der Satz möglicherweise nicht immer mit einem T beginnt - es ist nur der erste Buchstabe, der beim Einfügen nicht kapitalisiert / rekapitalisiert werden muss.

MetroidFan2002
quelle
23
Kopieren / Einfügen ist böse ... und zeitaufwändig. Diese Schritte sehen nach viel Arbeit aus. Wenn sich das Javadoc ändert, müssen Sie drei verschiedene Stellen aktualisieren. Ich glaube nicht, dass ein Plugin dies rechtfertigen würde ... zumindest, dann müsste das Plugin zB die Eigenschaft javadoc als Master betrachten und dann Getter (und Setter) überschreiben. Was ich erreichen möchte, ist, das Javadoc an einer einzigen Stelle zu schreiben und dann sowohl Getter als auch Eigenschafts-Javadocs dieselbe Beschreibung annehmen zu lassen ...
Normalerweise ändern sich Eigenschaften nicht allzu oft. Das Kopieren und Einfügen mit der automatischen Vervollständigung von Eclipse dauert weniger als 30 Sekunden, sobald die Eigenschaft Javadoc erstellt wurde.
MetroidFan2002
4
Ich bin nicht überzeugt ... Die Einführung dieser Art von Copy / Paste-Schema führt meiner Meinung nach zu Inkonsistenzen. Ich habe zu wenig Vertrauen in andere Köche (oder mich selbst), die den Code später bearbeiten. Zumindest wenn Sie kein vollständiges Design im Voraus haben, können sich die Javadoc-Eigenschaften häufig ändern, zumindest während einer Versuchs- / Entwurfsphase. Und Javadoc wird von besserer Qualität sein, wenn es geschrieben wird, wenn der Code frisch ist ... Entschuldigung, wenn ich wie ein Jammerer
1
Tut mir leid, aber das Bearbeiten von Eigenschaften führt zwangsläufig zu Inkonsistenzen. So oder so bleibt Javadoc auf der Strecke, es sei denn, es wird auf irgendeine Weise energisch gepflegt. Selbst wenn es eine einfache Möglichkeit gab, die Eigenschaft javadoc verfügbar zu machen, ist es genauso wahrscheinlich, dass die Eigenschaft javadoc selbst nicht aktualisiert wird. Es ist wirklich eine Frage der Codierungskonventionen des Teams usw. und der Codeüberprüfungen, so etwas - viel Glück für Sie, so mache ich das, damit ich es nicht vergesse.
MetroidFan2002
@Metroid - es sei denn, es wird auf irgendeine Weise energisch gepflegt - nun, es soll energisch gepflegt werden, wenn es als Teil des Quellcodes selbst behandelt wird. Und Javadoc-Kommentare (und deren Entsprechung in anderen Sprachen) nicht als Teil des Codes zu behandeln, obwohl dies leider die Standardpraxis ist, ist die Wurzel vieler Übel. Der schlimmste Kommentar ist der, der veraltet ist. Bestenfalls verlangsamen sie Programmierer daran, Code in den Griff zu bekommen (da sie veraltete Kommentare ständig neu validieren und akzeptieren / ablehnen müssen). Schlimmer noch, sie geben fehleranfällige, fehlerverursachende Informationen.
Luis.espinal
0

Ich denke wirklich, dass es ein Problem ist und der offizielle Javadoc-Leitfaden sagt nichts darüber aus. C # kann dies auf elegante Weise mit der Verwendung von Eigenschaften lösen (ich codiere nicht in C #, aber ich denke wirklich, dass es eine nette Funktion ist).

Aber ich habe eine Vermutung: Wenn Sie erklären müssen, was someString ist, ist es vielleicht ein "schlechtes kleines" an Ihrem Code. Es kann bedeuten, dass Sie SomeClass schreiben sollten, um someString einzugeben, damit Sie erklären, was someString in der SomeClass-Dokumentation ist, und nur damit die Javadocs in getter / setter nicht erforderlich sind.

Leonardo Leite
quelle
1
Informationen zur nicht ordnungsgemäßen Verwendung von Zeichenfolgen im Code finden Sie im Buch Effective Java unter "Vermeiden Sie Zeichenfolgen, bei denen andere Typen besser geeignet sind".
Leonardo Leite