Klasse dokumentieren: Tipps/Richtlinien?

Moin,

ich würde gerne wissen, ob ihr eure Klassen (über den uses) beschreibt, und wenn ja, nach welchem Schema ist diese Beschreibung dann aufgebaut?

Alles was ich hierzu gefunden habe war folgendes: automatische Kommentare in Klassen

Vielleicht habt ihr ja ein paar Tipps für mich, da ich meine Klassen schon gerne beschreiben würde. Evtl. gibt es ja auch hier Richtlinien?

Hi,

Wenn du wirklich Klassen meinst, dann sieh dir mal GhostDoc an!

Wenn du allerdings Dateien meinst, dann ändere einfach das Standard-Template oder erstell dir ein eingenes.
Die findest du unter folgendem Pfad: VS_DIR\Common7\IDE\ItemTemplates\CSharp\Windows Forms\1033\

Gruß, Christian.

Das ist doch ganz einfach

Eine "Demo" klasse erstellen, mit deinen Angaben füllen, und dann über File-> Export Template ein ItemTemplate daraus erstellen lassen, das kannst du dann immer auswählen bei "New Item".

Ist in ein paar Schritten erledigt.

Ich darf mal meine ungefragte Meinung zu GhostDoc sagen...
Man kanns schon nutzen. Dann sollte man allerdings seine Kollegen wirklich hassen und den nächsten Job schon in der Tasche haben 😉

Die Ergebnisse sind ja schon irgendwie ganz nett und überraschend, aber das Tool kann natürlich nicht mehr aus einem Methodennamen rausholen als der Leser es ohne großes Nachdenken selber schon unbewusst macht. Sprich, eine Methode namens TuEtwas wird mit "tut etwas" kommentiert. Mehr kann nicht gehen, das sollte man beachten.

Hallo chilic,

zur Generierung von XML-Kommentaren und zum Kommentieren von Events eignet sich GhostDoc allerdings sehr gut. Dass aus einer Methodensignatur DoSomething() keine umwerfende Dokumentation — und "Does Something." zähle ich mal nicht dazu — generiert werden kann, sollte ja nicht weiter verwundern 😉.

m0rius

Hi,

ich persönlich benutze auch gerne GhostDoc. Das, was dieses Tool standardmäßig generiert ist zwar meist etwas lasch, aber zusätzliche informationen, wie "hier kann null zurück gegeben werden" oder "hier wird unter bestimmten Umständen eine Exception geworfen" tippe ich dann je nach bedarf selber noch dazu.

Ein Schema für eine Klasse hatten wir in der Firma auch mal. Da Stand dann son Zeug drin wie Erstellungsdatum, Autor, Sinn der Klasse, alle Änderungen, ...
Das haben wir aber recht schnell wieder verworfen, weil das einfach keiner wirklich gelesen hat und somit dann mit der Zeit auch keiner mehr aktualisiert hat. Macht bei der Menge an Klassen in einem Projekt m. E. nicht wirklich Sinn. Aber liegt bei uns wahrscheinlich auch an dem verhältnismäßig eher kleinerem Team.

Gruß