Was soll ich in den Header der Klassendokumentation aufnehmen?

Ich suche nach einem informativen Klassendokumentationsformat für meine Entity-, Business Logic- und Data Access-Klassen.

Ich fand folgende zwei Formate von hier

Format 1

///-----------------------------------------------------------------
///   Namespace:      <Class Namespace>
///   Class:          <Class Name>
///   Description:    <Description>
///   Author:         <Author>                    Date: <DateTime>
///   Notes:          <Notes>
///   Revision History:
///   Name:           Date:        Description:
///-----------------------------------------------------------------

Format 2

// ===============================
// AUTHOR     :
// CREATE DATE     :
// PURPOSE     :
// SPECIAL NOTES:
// ===============================
// Change History:
//
//==================================

Ich habe das Gefühl, dass das Folgende die Grundelemente sind

• Autor
• Erstellungsdatum
• Beschreibung
• Änderungshistorie

als Namespace und Klassenname wird es sowieso geben.

Bitte teilen Sie mir Ihre Gedanken mit, welches Format empfohlen wird und ob es eine Standardmethode zum Schreiben des Revisionsverlaufs gibt.

Die meisten Informationen, die Sie dort vorgeschlagen haben, befinden sich im Quellrepository.

Das Einzige, was Sie wirklich brauchen, ist der Abschnitt "Zweck", in dem steht, wofür die Klasse da ist.

Wäre es mühsam, jedes Mal im Repository nachzuschauen, wenn Sie die anderen Informationen erfahren möchten? Ich würde nein sagen. Wie oft interessiert es Sie, wer der ursprüngliche Autor war? Oder wann die Datei zum ersten Mal erstellt wurde? Plugins (wie Ankh SVN für Visual Studio) ermöglichen es Ihnen häufig, mit der rechten Maustaste in Ihre aktuelle Datei zu klicken und das Repoistory-Protokoll für die Datei anzuzeigen. Daher ist es weniger mühsam, diese Informationen tatsächlich anzuzeigen.

Wenn Sie den Versionsverlauf in einem Kommentar speichern, muss dieser Kommentar außerdem beibehalten werden. Mit der Zeit besteht also die Möglichkeit, dass es Sie anlügt. Das Quellcode-Repository speichert diese historischen Daten automatisch, benötigt also keine Wartung und ist korrekt.

Beschreibende Klassen-, Methoden- und Variablennamen . Dies macht Kommentare wie Zweck und Beschreibung überflüssig. Manchmal denken wir, je kürzer der Methodenname, desto besser. Im Gegenteil, machen Sie einen Methodennamen so lange, wie Sie möchten, solange er seinen Zweck klar beschreibt. Halten Sie nur Notizen bereit, die absolut wichtig sind und das Codeverständnis in bestimmter Weise unterstützen. Wenn Programmierer Änderungen am Code vornehmen, vergessen sie häufig, Kommentare zu aktualisieren. Es kann passieren, dass Kommentare und Code nicht synchron sind und mehr Schaden als Nutzen anrichten.

Lesen Sie diesen Artikel von Jeff Atwood - Coding Without Comments .

Ich benutze Standard-Tags, um Dokumentation zu generieren. Nicht mehr, nicht weniger. Siehe hier

Ich gebe niemals Informationen ein, die nicht zur Klasse gehören. Verfasser, Daten und Revisionen sind Daten, die auf einem Versionskontrollsystem gespeichert werden sollen.

Die beiden vorgestellten Formate sind für die Generierung von Dokumentation nutzlos und weisen den größten Fehler bei Kommentaren auf. Sie listen den Revisionsverlauf auf.

Viele dieser Informationen können von Ihrem Quellcodeverwaltungs-Repository hinzugefügt werden, sodass Sie nur eine Beschreibung haben, die den Umfang und das Verhalten der Klasse genau beschreibt. Ich würde empfehlen, als Beispiel einen Blick auf einige Javadoc-Dateien für das Java-JDK zu werfen.

Alles in dieser Liste ist unnötig. Ihre Quellcodeverwaltung sollte sich um fast alles kümmern, und für das, was sie nicht abdeckt, sorgen gute Namenskonventionen.

Wenn ich deine "Beschreibung" lesen muss, um herauszufinden, was deine Klasse tut, dann hast du entweder (a) schlecht benannt oder (b) eine schlechte Klasse geschrieben, die zu viel tut (SRP).

Ich habe damit herumgespielt, meine Header-Vorlagen zu ändern, da, wie andere darauf hinweisen, viele dieser Informationen im Repository zu finden sind und die großen Felder, die ich bisher behalten wollte, die folgenden sind:

• Beschreibung - Was wird mit dem Code gemacht?
• Hinweise - Alles, was über den Code bekannt sein muss und nicht einfach aus den Kommentaren im Code selbst abgeleitet werden kann.
• Verweise - Verweise, von denen der Code abhängig ist, werden durch die Verwendung von includeoder ähnlichen Anweisungen nicht klargestellt .

Ein Punkt, der auch nützlich sein kann, ist ein Abschnitt über Schlüsselwörter. Während Sie möglicherweise nach Funktions-, Klassen-, Struktur- usw. Namen suchen können, gibt es einige Schlüsselwörter, die die anderen Namen in der Datei nicht klar machen. Für älteren, schlecht dokumentierten Code ist dies möglicherweise der erste Schritt zur Dokumentation des Codes für die Wartung.

Die meisten anderen Antworten, die ich bisher gelesen habe, gingen davon aus, dass es nur ein Repository gibt, das immer verfügbar ist

Da der Quellcode die Verbindung zum Repository verlieren kann (dh wenn er kopiert wird), sieht meine Klassendokumentation folgendermaßen aus:

• class documentation header (= der Kommentarblock am Anfang der Datei) enthält nur die erforderlichen rechtlichen Informationen (dh Copyright von xyz unter gpl-Lizenz)
• alles, was ein Entwickler, der die Klasse verwendet, wissen sollte, sollte in die class-java-doc-Kommentare (oder das .net-Äquivalent davon) aufgenommen werden, damit moderne Ideen diese Informationen als QuickInfo im Quellcode anzeigen können, der die Klasse verwendet.

Sie können auch die Ticketnummer für den Bugfix oder die Feature-Anfrage hinzufügen, damit Sie eine Ahnung haben, wo / wann / warum die Klasse erstellt wurde (wenn Sie das Glück haben, dass Sie auch nach einigen Jahren noch auf die Tickets zugreifen können).

Als ich gebeten wurde, Probleme in alten Closed-Source-Legacy-Programmen zu beheben, waren die Ticketnummern für mich sehr wertvoll, um die ursprünglichen Anforderungen des Codes zu verstehen.