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?
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?
Antworten:
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.
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.