DRY Weg, um Javadoc über Überladungsmethoden zu schreiben

9

Ich möchte Javadoc auf trockene Weise schreiben. Aber das Orakel-Dokument über Javadoc sagt, dass man dasselbe noch einmal in einen Kommentar zur Überladungsmethode schreiben soll. Kann ich Wiederholungen nicht vermeiden?

Sanghyun Lee
quelle

Antworten:

3

Ich streue {@inheritDoc}hier und da Anweisungen in meine Javadoc-Kommentare, wenn ich Methoden aus Oberklassen überschreibe oder schnittstellendefinierte Methoden implementiere.

Dies funktioniert zumindest für mich gut, vermeidet Wiederholungen im Quellcode und Sie können dem jeweiligen Javadoc-Kommentar dennoch spezifische Informationen hinzufügen, wenn dies erforderlich ist. Ich halte die Tatsache, dass der Javadoc-Kommentar selbst ziemlich kahl ist, nicht für ein Problem, wenn in einer anständigen IDE nur der Mauszeiger über den zugehörigen Bezeichnernamen bewegt werden muss, um den gerenderten Javadoc mit Referenzen und allem zu erhalten.

ein CVn
quelle
2

Der Dokumentationspunkt besteht darin, zukünftige Benutzer eines Elements zu beleuchten. Dies dient teilweise der Bequemlichkeit des Autors, so dass er oder sie nicht kontaktiert werden muss, wenn jemand nicht herausfinden kann, wie die Sache funktioniert. Meistens ist es jedoch zum Nutzen der Menschen, die das Ding nutzen oder unterstützen müssen.

Als solches sollte der Punkt Klarheit sein, im Gegensatz zu Bequemlichkeit für den Autor. Sie können nicht erwarten, dass Leute in Ihrer API-Dokumentation auf und ab gehen, weil Sie im Wesentlichen zu faul waren, um sich zu wiederholen. Saug es auf - Javadoc wird sich wiederholen.

Es gibt jedoch keinen Grund, wenn Sie klug sind, können Sie kein Programm schreiben, das Kommentare basierend auf Markierungen oder anderen Kriterien in Ihren Code einfügt. Es kann mehr Ärger sein, als es wert ist. Oder nicht.

Matthew Flynn
quelle
4
Nein, wiederhole dich nicht. Es ist nur viel mehr Aufwand, um alles synchron zu halten. Wenn es neue Informationen über die überladene Implementierung gibt, schreiben Sie nur diese. Ich denke, es ist vernünftig zu erwarten, dass Benutzer eines Typs die Javadocs seiner Supertypen betrachten, und Tools wie Eclipse machen es ihnen sehr einfach, dies zu tun.
Dawood ibn Kareem