Wie eine Methode zu dokumentieren, die eine andere Methode überschreibt?
Ich mich immer gefragt, wie eine Methode zu dokumentieren, der überschreibt eine Nachricht, die von einer Basisklasse.
Normalerweise füge ich ein java-doc an jede öffentliche Methode und einige private, protected-Methoden.
Aber autogenerating eine Dokumentation block für eine überschreibende Methode in eclipse erzeugt so etwas wie dieses:
/*
* (non-Javadoc)
*
* @see javax.swing.JComponent#paintComponent(java.awt.Graphics)
*/
Ist dies eine gute Möglichkeit zu dokumentieren, die überschreiben? Sollte ich Erben/kopieren Sie die Dokumentation von der Basis-Klasse?
Was werden Sie tun, als eine Dokumentation für diesen speziellen Fall?
Ich möchte einen überblick über die Verfahren, die verwendet werden.
- duplizieren: stackoverflow.com/questions/1081408/...
- Sie bearbeitet eine Frage, die ist so ziemlich genau das gleiche wie die, die Sie gerade gefragt? awesome, dude.
- Nicht wirklich... Hier ist deine +1 hinten
- Ich habe diese Frage in eine Führung für die Frage, aber dann dachte ich, meine Frage ist mehr allgemein und ein paar Leute kommentieren meine quetion in der Kommentar wäre von keinerlei nutzen für die person, die fragte, eine weitere spezielle Frage
- Andere Frage, die fragt, wie Erben und java-docs. Diese Frage fragt nach best practice
Du musst angemeldet sein, um einen Kommentar abzugeben.
Jede Methode - privat, geschützt, öffentlich -, sollten dokumentiert werden, die beschreiben, was es tut. Vergessen Sie Erben-Dokumentation, die von einer Basisklasse - Sie können eine Verknüpfung, um es, wenn Sie wollen, aber solange die Informationen dort, dass es eine geerbte Methode überschreibt dann die andere person ist frei, um suchen es für sich selbst. DRY - don ' T repeat yourself - Dokument die Basis-Methode der Klasse nur an einem Ort.
Ich weiß nicht einmal denke, es ist gut zu dokumentieren, Wann welche Methode überschreibt, denn das kann sich ändern, und es wird schwer sein, um es aktuell zu halten, wenn Sie legen Sie neue Klassen in der Hierarchie zwischen Ihrer Klasse und der Basisklasse. Einfach die information, dass es überschreibt eine vererbte Methode ist ausreichend.
Wenn Ihre Methoden sind zu Komplex, um Dokument in ein paar Zeilen Kommentare, dann sind Sie wahrscheinlich zu Komplex und sollte umgestaltet werden.
einschließlich der @Override-annotation werden sollte, genügt ein neugieriger Entwickler das super.