it-swarm.com.de

Javadoc @author-Tag bewährte Methoden

Ich wundere mich über Best Practices beim Erstellen von Javadocs. Ich habe ein Projekt mit vielen Dateien. Code wurde von vielen Entwicklern erstellt. Jede Datei hat eine Anmerkung @author, es ist also offensichtlich, wer eine bestimmte Klasse erstellt hat. 

Wenn jedoch ein anderer Entwickler einer Datei neuen Code hinzufügt, ändert usw., wie sollte er den Rest des Teams darüber informieren, dass er eine neue Funktion erstellt oder bereits vorhandenen Code geändert hat? Mit anderen Worten, wie sollten wir "die Javadocs mit der Realität kompatibel halten"? ;)

  • Seinen namen zu dem @author-tag hinzufügen? Dann ist es einfacher zu ermitteln, wen Sie im Zweifel fragen müssen.
  • Hinzufügen eines @author-Tags zu jeder neuen Methode, inneren Klasse usw.?

Da wir SVN verwenden, ist es natürlich leicht zu untersuchen, wer was gemacht hat, aber um die Dinge klar zu halten, sollte auch dieses Javadoc-Zeug in Betracht gezogen werden.

Was ist der beste Weg, diese @author-Tags zu verwenden?

56
guitar_freak

Ich würde sagen, dass @author für die meisten Zwecke unerwünschtes Rauschen ist. Der Benutzer Ihrer API sollte sich nicht darum kümmern oder wissen wollen, wer welche Teile geschrieben hat.

Und wie Sie bereits gesagt haben, hält SVN diese Informationen bereits viel autoritärer als der Code. Wenn ich also zum Team gehörte, würde ich immer das Protokoll von SVN vorziehen und den @author ignorieren. Ich würde wetten, dass der Code nicht mit der Realität übereinstimmen wird, egal welche Politik Sie gewählt haben. Warum sollten Sie diese Information an zwei Stellen aufbewahren?

Wenn jedoch aus bürokratischen oder politischen Gründen MUSS diese Informationen in den Code aufgenommen werden MÜSSEN, haben Sie in Erwägung gezogen, das @author-Tag beim Einchecken automatisch zu aktualisieren? Sie könnten wahrscheinlich dies mit einem SVN-Hook erreichen. Sie können beispielsweise alle Entwickler auflisten, die eine bestimmte Datei in der Reihenfolge geändert haben, in der sie sie geändert haben. oder wer es am meisten verändert hat; oder Wasauchimmer. Wenn der @author in dem von Ihnen freigegebenen (Quell-) Code vorgeschrieben ist, können Sie den @author automatisch als Teil des Release-Builds hinzufügen.

Wenn Sie mehr als ein einzelnes @author-Tag (oder einen anderen Kommentar) auf Klassenebene hinzufügen möchten, würde ich sagen, dass Sie eine Menge nicht hilfreicher Geräusche ansammeln würden. (Wieder haben Sie SVN.)

Nach meiner Erfahrung ist es viel sinnvoller, eine historische Änderung zu identifizieren (beispielsweise eine Änderung einer Codezeile oder einer Methode), um dann herauszufinden, auf welchen Änderungssatz sich dies bezieht (und auf welches Track-Ticket). Dann haben Sie den vollständigen Kontext für die Änderung: Sie haben das Ticket, das Änderungsset, Sie können andere Änderungssets für dasselbe Ticket finden oder ungefähr zur gleichen Zeit, Sie können verwandte Tickets finden und ALLE Änderungen sehen bildete diese Arbeitseinheit. Sie erhalten dies niemals durch Anmerkungen oder Kommentare im Code.

56
Paul

Vielleicht möchten Sie warum als Autor-Tags in der Quelle betrachten. Die Apache Foundation stimmt nicht und ich stimme zu.

http://www.theinquirer.net/inquirer/news/1037207/Apache-enforces-the-removal-of-author-tags

Meines Erachtens ist dies eine Art Frachtkult, wenn die Quellen auf Papier gedruckt wurden. Mit modernen Versionskontrollsystemen können diese und andere Informationen ohnehin in der Geschichte gefunden werden.

Sie können mehrere @author-Tags haben. Wenn Sie große Änderungen an einer Klasse vornehmen, fügen Sie einfach einen neuen @author-Tag mit Ihrem eigenen Namen hinzu. Sie müssen die Änderungen, die Sie vorgenommen haben, nicht markieren oder Ihren Namen in die Änderungen einbeziehen, da der Revisionsverlauf dies klar anzeigen kann.

8
Juned Ahsan

In wirklich großen und lang laufenden Projekten mit vielen Entwicklern ist es nützlich zu wissen, dass er für den angegebenen Code verantwortlich ist und wer Ihnen zusätzliche Informationen und dergleichen geben kann. In diesem Fall wäre es praktisch, solche Informationen mit dem @author-Tag in der Datei zu haben. Dabei wird nicht angegeben, wer die Datei erstellt hat oder wer wichtige Beiträge geleistet hat, sondern wer für diesen Code eine Kontaktperson ist. Dies können sehr unterschiedliche Personen sein, da der ursprüngliche Autor sich bereits in einem anderen Projekt befindet oder das Unternehmen vor Jahren verlassen hat.

Ich denke, bei einem großen Projekt mag dieser Ansatz praktisch sein, es gibt jedoch einen Vorbehalt. Es ist sehr schwierig, die Autoreninformationen jeder einzelnen Datei beizubehalten, da sehr viele Dateien vorhanden sind und früher oder später ein Fehler auftritt. Immer mehr Dateien verfügen über veraltete Informationen und Entwickler werden diesem @Autor nicht mehr als Informationsquelle trauen und sie einfach ignorieren.

Die Lösung, die möglicherweise funktioniert, besteht darin, @author nicht für jede einzelne Datei zu behalten, sondern nur pro Modul (High-Level-Pakete). Javadoc verfügt über eine Funktion, mit der Sie nicht nur Dateien, sondern ganze Pakete dokumentieren können ( Weitere Informationen finden Sie in dieser Frage ).

Dies ist jedoch ein Sonderfall, und solange Ihr Projekt nicht so groß oder alt ist, empfehle ich Ihnen, die Informationen des Autors zu veröffentlichen.

7
Vojtech Ruzicka

Ich stimme völlig zu, dass dies unnötig ist und Sie sollten es wahrscheinlich nicht hinzufügen. Trotzdem füge ich es immer noch hinzu. Ich sehe es so, als würde man einem Gemälde eine Signatur hinzufügen oder einem Stempel auf einem Metallstück in einem Computer hinzufügen, was beim Entwerfen eines Computers geholfen hat . Sie haben dieses Stück Code geschrieben, und das Hinzufügen Ihres Namens zeigt, dass Sie stolz darauf sind und sich auf seine Qualität verlassen können, auch wenn es sonst nichts tut. Selbst wenn es in der Zukunft geändert wurde, haben Sie die Grundlagen für alles, was darauf aufgebaut ist, geschaffen. Sollte es wirklich komplett neu geschrieben werden, kann das Tag geändert, entfernt oder erweitert werden. Ich bin damit einverstanden, dass es dank der Versionskontrolle überflüssig ist, aber wenn Sie Ihren Namen in der Versionskontrolle haben, ist dies bei weitem nicht zufriedenstellend. Wenn jemand nur ein "final" hinzufügt oder den Code formatiert, wird sein Name in Versionskontrolle gestellt, auch wenn er kaum einen Beitrag leistet. Ich stimme auch zu, dass es sich dabei um Rauschen handelt, da es dem Code nichts hinzufügt. Ist es wirklich sogar etwas auffällig nervig? Ich glaube nicht Wenn Sie vernünftig sind, denke ich, kann es ein Projekt "freundlicher" machen, wenn dies sinnvoll ist.

1

Es ist sehr praktisch, ein @author-Tag zu haben und mehrere Autoren zu haben. Sogar die Dokumentation von Oracle beschreibt, dass es eine gute Praxis ist, @author an der Spitze der Klasse zu haben, um den Autor, der die Aufgabe erledigt hat, zu würdigen und auch Dinge aufzuspüren, wenn während des Entwicklungsprozesses jemand angesprochen werden muss. Wenn mehrere Autoren vorhanden sind, können sie in der Reihenfolge aufgeführt werden, in der sie zu einer bestimmten Java-Datei/Klasse beigetragen haben. Ja, es gibt Plugins und mit git-Struktur können Sie den Namen des Autors genau im Code sehen, aber diese Idee wird jedoch kontrovers sein. Manchmal bearbeiten mehrere Autoren dieselbe Codezeile und zeigen möglicherweise nicht zwei Autoren an, die dieselbe Codezeile bearbeiten. Ich habe das Plugin aktiviert, es zeigt nie den Namen eines Autors für die Bearbeitung derselben Codezeile. Bei großen Unternehmen ist es praktisch, diese Praxis einrichten zu lassen.

0
surendrapanday

Wenn es sich um einen Buchungskreis handelt, würde ich das nicht tun: Wir haben VCS. Wenn es sich stattdessen um einen Blogbeitrag oder Codeausschnitte meines persönlichen Repos handelt, würde ich dies stolz hinzufügen und hoffen, dass jemand, der mit Kopieren und Einfügen arbeitet, meinen Code nützlich findet und versehentlich auch meinen Namen kopiert :)

Nur meine Art von Humor, denke ich.

0
WesternGun