Laden...

Quellcode dokumentieren [API- und Quellcodedokumentation]

Erstellt von Coooder vor 12 Jahren Letzter Beitrag vor 12 Jahren 13.538 Views
C
Coooder Themenstarter:in
180 Beiträge seit 2011
vor 12 Jahren
Quellcode dokumentieren [API- und Quellcodedokumentation]

hallo leute, 😃

ich habe festgestellt das ich es gar nicht so einfach finde quellcode zu documentieren.
Immer wenn ich ein entsprechendes kommentar schreiben will, denk ich mir, das steht doch schon da o.O
ich versuche nähmlich die funktionen nach deren aufgabe zu benennen, aber deswegen weiss ich auch nicht wie ich es kommentieren soll

könnt ihr mir sagen wie man da am besten ran geht? wäre super 😃

A
764 Beiträge seit 2007
vor 12 Jahren

Robert C Martin schreibt in seinem Buch: Clean Code, dass man Kommentare vermeiden soll. Und zwar indem man den Code aussagekräftig genug schreibt.

Edit: Aber das ist sicherlich ein Punkt, über den man streiten kann.

16.806 Beiträge seit 2008
vor 12 Jahren

Ich weiß jetzt nicht, was Du hören willst, aber kennst Du Mit Kommentaren im C#-Code wird die Dokumentationserstellung zum Kinderspiel

Hilfsmittel zu Erstellung von Kommentaren bzw. zu Dokumentationbibliotheken sind zB GhostDoc und SandCastle Helpfile Builder.
Wie umfangreich und auf welche Art und Weise man Code dokumentiert, siehst Du doch anhand der MSDN.

Wenn es um inhaltliche Methoden-Kommentare geht, dann dokumentiert man nur dort, wo man zB bestimmte Vorgänge erklären will; aber sicherlich nicht jede Ausführung oder Deklaration. Hier ist weniger mehr.

S
269 Beiträge seit 2010
vor 12 Jahren

Ich kann dazu nur sagen, dass auch hier in der Firma die Philosophie "der Methodenname sagt aus, was die Methode macht" gefahren wird.
Demnach finden sich nicht allzu viele Kommentare in unseren Projekten, und waren bisher auch nicht nötig.

Mitunter sind Konstanten mit <summary> versehen, weil der Name mitunter zu lang werden würde, um zu beschreiben, was letztendlich in der Konstanten steht, aber auch das ist selten der Fall.

Die meisten Kommentare in den Projekten hier sind eigentlich Anmerkungen zu Änderungen am Quellcode im Format
//<Programmierer-Kürzel> <Datum> <Änderungsanmerkungen/-hinweise/-gründe>
und die halte ich dann sogar für sinnvoll!

so far
Karill Endusa

B
357 Beiträge seit 2010
vor 12 Jahren

/// <summary>
ist wohl einer der besten Wege die Funktion einer Methode zu dokumentieren. Wird hier alles schön angegeben mit einer kurzen Beschreibung, Parametern und Rückgabewerten, lässt sich damit nämlich mit wenigen Klicks eine komplette Dokumentation erstellen, ganz zu schweigen von den Infos, die die Kollegen dann durch Intellisense schon mitbekommen.

D
500 Beiträge seit 2007
vor 12 Jahren

Man muss sicherlich zwischen Code Dokumentation und API Dokumentation unterscheiden. Eine API Dokumentation kann gar nicht aussagekraeftig und ausfuehrlich genug sein.

Fuer Kommentare im Code halte ich es aehnlich wie Abt:

Wenn es um inhaltliche Methoden-Kommentare geht, dann dokumentiert man nur dort, wo man zB bestimmte Vorgänge erklären will; aber sicherlich nicht jede Ausführung oder Deklaration. Hier ist weniger mehr.

Um es noch verkuerzter zu schreiben: Dokumentiere warum Du etwas an einer Stelle machst und nicht was, denn das steht bereits als Code da.

Gruss,
DaMoe

C
2.121 Beiträge seit 2010
vor 12 Jahren

Ich kann mir ehrlich gesagt nicht vorstellen dass ein größeres Projekt ohne Kommentare im Code auskommt.
Spätestens Sonderfälle in einer Methode gehören doch in den Methodenkommentar. Oder kann man sich vor Verwendung einer Methode wirklich immer anschauen was die macht, inklusive allen weiteren verschachtelten Aufrufen?
Dann gibts ja noch die Kommentare die komplexere Algorithmen erklären.

2.207 Beiträge seit 2011
vor 12 Jahren

Hallo zusammen,

im Clean-Code-Sinne: Jede Methode hat nur eine Aufgabe und der Methodenname ist aussagekräftig gewählt, dann ist es sogar gut, dass man auf den ersten Blick keine Kommentare schreiben kann. Ich erwische mich auch manchmal dabei, dass ich welche schreiben "muss". Dann kommt aber gleich der Gedanke daran, dass ich die Methoden besser hätte formulieren können/müssen.

Wenn es um eine API geht, gibt es Plugins für das VS, die das ganz gut dokumentieren ...ich hab grad den Namen nicht im Kopf...es liegt mir auf der Zunge. Dann kann man auf die Methode rechtsklicken --> "Document this"...vielleicht kennt das ja einer.

Wenn ich "alten" Code anschaue und Kommentare dazu lese fallen mir häufig Wege ein, es so umzuschreiben, dass man die Kommentare nicht bruacht. Oftmal vergisst man sie anzupassen und mitzuwarten, wenn man z.B. Refactoring durchführt.

Gruss

Coffeebean

16.806 Beiträge seit 2008
vor 12 Jahren

Dann kann man auf die Methode rechtsklicken --> "Document this"...vielleicht kennt das ja einer.

Hab ich bereits genannt. GhostDoc.

C
2.121 Beiträge seit 2010
vor 12 Jahren

GhostDoc ist aber ja schon wirklich die größte Verarschung jedes Mitmenschen, der diesen so "kommentierten" Quellcode mal anschauen muss 😉

16.806 Beiträge seit 2008
vor 12 Jahren

Begründung?

5.742 Beiträge seit 2007
vor 12 Jahren

Die meisten Kommentare in den Projekten hier sind eigentlich Anmerkungen zu Änderungen am Quellcode im Format
//<Programmierer-Kürzel> <Datum> <Änderungsanmerkungen/-hinweise/-gründe>
und die halte ich dann sogar für sinnvoll!

Gehört IMHO nicht in den Quellcode, sondern in die Versionsverwaltung.

Begründung?

Ich sag' nur:

Get's the name of the first

Also Nacharbeiten muss man definitiv und nicht einfach mit GhostDoc dokumentieren 😉

Aber siehe generell auch Richtlinien für Kommentare sowie Sollte alles im Code kommentiert werden?
Wenn möglich bitte hier nur neue Aspekte posten, die in den genannten Threads nicht bereits diskutiert wurden.

C
2.121 Beiträge seit 2010
vor 12 Jahren

Aus DoSomething wird bestenfalls der Kommentar "does something". SaveSettings wird zu "saves the settings" und so weiter. Das Teil kann höchstens das aus einem Namen herausziehen was jeder Mensch sowieso gedanklich macht.

Wenn jemand alles nur so kommentiert (RechnungDrucken() -> "Druckt Rechnung"), frag ich ihn ob er nen Clown zu viel gefressen hat. Wo ist da der Sinn?

Manches ist im jeweiligen Kontext wirklich selbstklärend. Da schreib ich dann auch nichts mehr dazu. Aber oft gibts eben mehr zu wissen als dass X auch tatsächlich X bedeutet.

C
1.214 Beiträge seit 2006
vor 12 Jahren

Wenn jemand alles nur so kommentiert (RechnungDrucken() -> "Druckt Rechnung"), frag ich ihn ob er nen Clown zu viel gefressen hat. Wo ist da der Sinn?

Ich weiß nicht, wozu die ganze Diskussion gut sein soll. Ich glaube, ob, wie und warum man Kommentare schreiben sollte, wurde schon oft genug besprochen, nicht nur hier im Forum. Solche Kommentare wie oben schreibe ich nicht. Wenn sie jemand doch schreibt, von mir aus, stört mich auch nicht. Aber bei jedem komplexen Projekt gibt es mehr als genug Stellen, die man ausführlich dokumentieren muss. Es gibt Funktionen, die ein komplexes Verhalten aufweisen, das man kommentieren muss, ebenso die Parameter, und auch in einer Funktion selbst gibt es häufig genug Abläufe, die man einfach dokumentieren muss. Ich kaufe Martin C Robert nicht ab, dass man einfach jede Funktion in selbsterklärende Unterfunktionen zerlegen kann und schon muss man nichts mehr kommentieren. Das ist einfach Quatsch. Das geht bei 0815 Code, gettern und settern und sonstigem, aber jedes halbwegs komplexe System muss sowohl die Schnittstelle als auch die Implementierung in Form von Kommentaren dokumentieren, sonst ist es nicht wartbar.
Zu allen anderen Vorschlägen, wie Commit Kommentare kann ich nur sagen, dass sie eigentlich keinen interessieren. Wenn ich programmiere, will ich inline Infos haben, am besten in Form von Intellisense. Ich mag da nicht irgendwelche externen Dokus aufmachen und schon gar nicht im Versionsverwaltungslog schauen.

S
269 Beiträge seit 2010
vor 12 Jahren

Gehört IMHO nicht in den Quellcode, sondern in die Versionsverwaltung. Ich nur Azubi, ich nix angeschlossen an Versionsverwaltung (welche im Übrigen auf dem Entwickler-Rechner meines Ausbilders läuft, welches ein Laptop ist, welches nur hier ist wenn er auch da ist)

Gelöschter Account
vor 12 Jahren

GhostDoc empfinde ich auch eher als Krankheit denn als hilfe. Die meisten, die das verwenden, tun dies um eine automatisch erfasste Dokumentationsabdeckung zu befriedigen und das ist nicht der Sinn von Kommentaren.

Generell gehört meiner Ansicht nach in die Summary die Frage nach dem "was tut die Methode" beantwortet und innerhalb der Methode die Frage nach "warum ist das so wie es ist" beantwortet.

Allgemein verständliche Methoden/Properties kommentiere ich nicht. Sowas wie SaveSettings z.B. ist meistens keinen Kommentar wert. Das erhöht nur das Rauschen im Code und kostet Zeit beim Schreiben.

49.485 Beiträge seit 2005
vor 12 Jahren

Hallo zusammen,

bitte hier nur neue Aspekte posten, die in den genannten Threads nicht bereits diskutiert wurden.

das finde ich ebenfalls wichtig. Deshalb konzentriere ich mich hier auf folgendes:

Die Diskussion um GhostDoc zeigt doch sehr schön, dass die Aussage

Clean Code, dass man Kommentare vermeiden soll. Und zwar indem man den Code aussagekräftig genug schreibt.

dringend auf den Prüfstand gehört. Denn die Kommentare, die GhostDoc aus dem Quellcode zieht, haben den gleichen Informationsinhalt, wie der Quellcode selbst (genauer: wie die Teile des Quellcodes, die GhostDoc als Basis für die Kommentare heranzieht). Wenn man also zu der Einschätzung kommt, dass man die Kommentare von GhostDoc vergessen kann, dann doch nur deshalb, weil im Quellcode eben doch nicht genug Information gesteckt hat und deshalb zusätzliche Informationen in Form von (selbst geschriebenen) Kommentaren erforderlich sind. Sicher ist sprechende Quellcode ein schönes und sinnvolles Ziel und man sollte sich immer darum bemühen. Anderseits stelle ich die These auf, dass Kommentare dadurch nicht entbehrlich werden, wie eben die GhostDoc-Diskussion sehr schön zeigt. Ich halte das Argument "Clean Code braucht keine Kommentare" für Augenwischerei bzw. für eine willkommene Ausrede für Dokumentationsmuffel.

Wenn ich "alten" Code anschaue und Kommentare dazu lese fallen mir häufig Wege ein, es so umzuschreiben, dass man die Kommentare nicht bruacht

Was aber eben auch bedeutet, dass das Nachdenken über den Code durch die Dokumentationsbrille, den Blick dafür schärft, welche Informationen relevant sind. Es macht also durchaus Sinn, auf den Code nicht nur durch die Implementierungsbrille zu schauen, sondern auch durch die Dokumentationsbrille, selbst wenn man am Ende doch keine Kommentare schreibt, sondern stattdessen "nur" den Quellcode lesbarer macht.

Ansonsten hat DaMoe80einen wichtigen Punkt genannt:

Man muss sicherlich zwischen Code Dokumentation und API Dokumentation unterscheiden.

Um Missverständnisse zu vermeiden, sollte ihr also immer dazu sagen, worüber ihr gerade redet.

herbivore

S
211 Beiträge seit 2010
vor 12 Jahren

Ich verstehe sowieso nicht wieso viele denken sie schreiben Kommentare um zu beschreiben was eine Methode/Funktion macht.

Es wurde ja schon mehrmals gesagt, WAS eine Methode macht kann man am Mehodennamen (sofern er sinnvoll gewählt ist) ablesen.

Ich finde Kommentare sollte man schreiben WARUM macht etwas macht. Weil was bringt es mir wenn ich mich durch tonnenweise Quellcode wühle, alle Methoden wunderbar beschrieben indem was sie machen, ich aber ständig überlege: "wieso ruft er da jetzt diese Methode auf ?" oder "wieso erzeugt er da jetzt ein neues Objekt, er hat doch schon eines".

Ob das jetzt an Unwissenheit liegt, an stark unterschiedlichen Programmierstilen oder was auch immer. Ich finde kommentiere sollte man hauptsächlich WARUM man etwas tut und nicht WAS. Weil das Was sieht man auch im Code (meistens).

C
2.121 Beiträge seit 2010
vor 12 Jahren

Was so ungefähr passiert, steht in der Tat im Namen. Aber Details eben nicht. Man nennt seine Methoden ja nicht DruckeDieRechnungOderWirfEineExceptionWennDieÜbergebeneIdUngültig ist ...

@scrabbl:
Man sollte beides in Maßen tun. Wenn nicht klar ist was in einem Stück Code passiert oder warum was aufgerufen wird, schreibt mans hin. Aber das ist ein anderer Kommentar als bei der Deklaration von etwas.

Man kanns wie überall über- oder untertreiben.
Ich denke genaue Regeln kann man dafür nicht aufstellen. Das ist fallabhängig und muss von jedem individuell entschieden werden.
Ich find nur wichtig dass man keine sinnlosen Regeln aufstellt, wie auf jeden Fall immer alles kommentieren, oder überhaupt nichts. Oder eben Pseudokommentare erzeugen lassen, damit irgendjemand zufrieden ist.
Mitdenken wird auch in Zukunft gefragt sein 😉

5.742 Beiträge seit 2007
vor 12 Jahren

(Zu API-Dokumentationen:)

Wenn man also zu der Einschätzung kommt, dass man die Kommentare von GhostDoc vergessen kann, dann doch nur deshalb, weil im Quellcode eben doch nicht genug Information gesteckt hat und deshalb zusätzliche Informationen in Form von (selbst geschriebenen) Kommentaren erforderlich sind.

Das ist nicht der einzig mögliche Schluss, den man daraus ziehen kann:
GhostDoc Kommentare bringen vielmehr keine zusätzlichen Informationen und sind folglich redundant.

Man nennt seine Methoden ja nicht DruckeDieRechnungOderWirfEineExceptionWennDieÜbergebeneIdUngültig ist ...

Ja - ich denke das macht nochmal deutlich, was nicht in den Methodennamen gehört:
Zustände, in denen man die Methode aufrufen bzw. nicht aufrufen darf sowie gültige Wertebereiche für Parameter.

Diese formuliert man m.E. aber besser mit Code Contracts oder Vergleichbarem, dass die auch tatsächlich geprüft werden (und nicht nur so im Raum stehen).

Insofern kann Clean Code die API Dokumentation also schon einmal deutlich verschmälern.
Ob er sie ersetzen kann, hängt dann m.E. vom jeweiligen Projekt ab.

L
667 Beiträge seit 2004
vor 12 Jahren

Es gibt meiner Meinung nach keinen einzigen Grund, der dafür spricht, Kommentare einzusparen. Je mehr Kommentare, desto besser. Selbst wenn es nur Stating-The-Obvious ist, für den einen mögen Sachverhalte offensichtlich sein, für einen anderen, der einen Fremdcode vorgesetzt bekommt, vielleicht nicht. Hingegen sehe ich keine Nachteile in mehr Kommentaren, im schlechtesten Fall bringt ein Kommentar keinen Mehrgewinn, dann schadet er aber auch nicht.

Leider suchen viele immer nach Argumenten, warum Kommentare schlecht sind oder warum Kommentierung überflüssig ist, das liegt dann aber in 100% der Fälle an der Faulheit der Leute, die aber dann gern am Firmenstammtisch über den Code von jemand anderem herziehen "Voll scheiße, alles endlos verzweigt, nix kommentiert... wie soll man da denn durchblicken..."

"It is not wise to be wise" - Sun Tzu

5.742 Beiträge seit 2007
vor 12 Jahren

Es gibt meiner Meinung nach keinen einzigen Grund, der dafür spricht, Kommentare einzusparen.

Doch!

Auch Kommentare müssen gepflegt werden - sonst hat man ganz schnell Fälle, in denen sich Kommentare und Code widersprechen.
Und was gilt dann?

Folgende Deklarationen sind eindeutig:


//In Millisekunden
int time;

int timeInMilliseconds;

Aber was ist hiermit?


//In Sekunden
int timeInMilliseconds;

Hier hat der Kommentar die Lesbarkeit des Codes verschlechtert.

Zudem sind Kommentare IMHO auch ein gewisses "Rauschen" im Code.

Und ob ich jetzt folgende Methode habe:


bool Exists(string item)
{
   for (int i = 0; i < list.Length; i++)
   {
      if (list[i] == item)
         return true; 
   }
   return false;
}

Oder folgende:


//Die Methode Exists. Sie gibt ein bool (System.Boolean) zurück, welches die Werte "true" oder "false" annehmen kann. Ein Boolean kann z.B. in einer if-Abfrage ausgewertet werden. Alternativ kann man das Ergebnis einer Variablen zuweisen.
//Die Methode erwartet einen Parameter vom Typ string, der "item" heißt - ein String beinhaltet eine Zeichenfolge - z.B. "Hallo" oder "Hallo Welt". Dabei kann entweder eine zuvor deklarierte und initialisierte Variable vom Typ String übergeben werden oder direkt ein Stringliteral.
//Die Methode wird aufgerufen, indem man den Methodennamen gefolgt von einem Klammernpaar schreibt, in welchem die Parameter notiert werden.
//Beispiel:
//Ein Aufruf mit Übergabe einer Variablen:
//string s = "Test";
//Exists(s);
//Ein Aufruf mit Übergabe eines Literals:
//Exists("Test");
bool Exists(string item) //Der Methodenkopf mit Rückgabetyp, Name und Parametern
{ //Die Klammer, die den Methodenrumpf eröffnet
   //Der Methodenrumpf: Hier steht der Code, der ausgeführt wird, wenn die Methode aufgerufen wird.
   //Er wird von oben nach unten ausgeführt.
   //Der Parameter "item" (siehe oben) kann hier verwendet werden wie eine Variable. Ihr Wert ist allerdings mit dem übergebenen Wert vorbelegt.
   //Eine for-Schleife: Diese wiederholt Code, der darin steht anhand vorgegebener Rahmenbedingungen
   for /*Das Schlüsselwort for, welches die Schleife einleitet*/ ( /*Die Initialiserung: Dieser Code wird einmalig vor der ersten Prüfung der Bedingung ausgeführt. In diesem Fall deklarieren wir eine Variable vom Typ int und initialisieren sie mit dem Wert 0. Ein Integer kann Ganzzahlen im Bereich von -2hoch31 bis 2hoch31 - 1 aufnehmen. In dieser Schleife fangen wir jedoch bei 0 an*/ int i = 0 /*Ein Semikolon:*/; /*Die Schleifenbedingung: Diese wird vor jedem Schleifendurchlauf geprüft. Nur, wenn sie true ergibt, wird der Code innerhalb des Schleifenrumpfes ausgeführt. Andernfalls wird die Schleife beendet. An dieser Stelle wird i (=die Schleifenvariable) mit der Länge der Liste verglichen. Nur, wenn i noch kleiner als die Länge der Liste ist, wird die Schleife erneut ausgeführt*/ i < list.Length; /*Code, der nach jedem Schleifendurchgang ausgeführt wird - hier wird i um eins erhöht (gleichbedeutend mit "i = i +  1" bzw. "i += 1" */ i++)
   { //Der Schleifenrumpf, der den zu wiederholenden Code enthält:
      //... (jetzt reicht's mir :-D)

Ich bevorzuge erstere Variante - du letztere?

L
667 Beiträge seit 2004
vor 12 Jahren

Naja, Du kannst Deine Methode ja auch mit Brainfuck.NET programmieren, dann kann den ach so simplen Code auch niemand mehr entziffern. Will sagen, Dein Beispiel ist albern... wenn jemand anfängt zu kommentieren, was ein Semikolon bedeutet, gehört er eher ans Fließband als vor einen PC. Und bei einem Kommentar für jedes Wort eine eigene Zeile zu benutzen oder alle Kommentare in den Code rein zu packen ohne Zeilenumbruch hat eher mit Sabotage als mit konstruktiver Arbeit zu tun.

Genausogut könntest Du den Code selbst, der ohne Kommentare auskommt, so beschissen formatieren und mit sinnlosen Operationen auffüllen, dass Du Deine Argumentation umkehren kannst.

"It is not wise to be wise" - Sun Tzu

5.742 Beiträge seit 2007
vor 12 Jahren

wenn jemand anfängt zu kommentieren, was ein Semikolon bedeutet, gehört er eher ans Fließband als vor einen PC.

Genau - ich hab ja folgendes nie behauptet: 😉

Je mehr Kommentare, desto besser

49.485 Beiträge seit 2005
vor 12 Jahren

Hallo Lynix,

Hingegen sehe ich keine Nachteile in mehr Kommentaren, im schlechtesten Fall bringt ein Kommentar keinen Mehrgewinn, dann schadet er aber auch nicht.

obwohl ich ein klarer Befürworter von Kommentaren bin, ist es offensichtlich falsch, dass Kommentare keine Nachteile haben.

  • Es fängt damit an, dass es (Arbeits-)Zeit kostet, Kommentare zu erstellen.
  • Dann müssen Kommentare an Codeänderungen angepasst werden, die müssen also aktuell gehalten werden.
  • Das kann vergessen werden und zu Inkonsistenzen führen.
  • Wenn die Änderungen nicht vergessen werden, kosten sie erneut Zeit.
  • Je mehr und je längere Kommentare existieren, desto mehr Zeit kosten die Aktualisierungen und desto eher übersieht der Änderer notwendige Aktualisierungen.
  • Selbst wenn Kommentare keine überflüssigen Informationen enthalten, können sie den Code auseinander ziehen/reißen und dadurch die Übersichtlichkeit verringern.
  • Selbst mit guter Absicht und Sorgfalt erstellte Kommentare können inhaltlich falsch oder missverständlich formuliert sein und dadurch schaden.
  • Selbst in mit guter Absicht und Sorgfalt erstellten Kommentare können gerade die Informationen fehlen, die ein späterer Leser mit einem anderen Erfahrungshintergrund benötigt.

Das alles kannst du nicht ernsthaft bestreiten, zumindest kannst du nicht bestreiten, dass gewisse Nachteile existieren. Wenn man also Kommentare schreibt, dann nicht deshalb, weil es keine Nachteile gibt, sondern weil die Vorteile die Nachteile überwiegen. Und genau dieser Überzeugung bin ich.

Die Nachteile von Kommentaren zu kennen und zu akzeptieren, ist übrigens kein Nachteil. Im Gegenteil kann man nur dann gezielt dran arbeiten, die Nachteile zu vermeiden oder zumindest möglichst gering zu halten.

Hallo winSharp93,

Das ist nicht der einzig mögliche Schluss, den man daraus ziehen kann:
GhostDoc Kommentare bringen vielmehr keine zusätzlichen Informationen und sind folglich redundant.

es liegt in der Natur des Sache, dass selbst API-Kommentare vielfach redundant zu den Informationen sind, die im Quellcode stecken. Das liegt aber nicht an GhostDoc, sondern daran, dass die API-Dokumentation eine anderen Zielgruppe, nämlich die Benutzer der Klassenbibliothek, adressiert und diese den Quellcode nicht kennen und nicht kennen sollen. Stattdessen gibt man ihnen eine natürlichsprachliche Dokumentation.

Und selbst selbst wenn man weitere Schlüsse aus den Fakten ziehen kann, bedeutet das nicht, dass mein Schluss, falsch ist. Für mich gilt weiterhin, dass die GhostDoc Diskussion zeigt, dass die pauschale Aussage "Clean Code braucht keine Kommentare" falsch ist.

Davon abgesehen halte ich GhostDoc nicht für ein Tool, dass automatisch eine komplette und fertige API-Dokumentaion erstellt, sondern nur für eins, dass einen Rahmen erzeugt, den man noch mit vielen Informationen ergänzen muss, siehe meine Antwort an Lynix.

Hallo scrabbl,

Es wurde ja schon mehrmals gesagt, WAS eine Methode macht kann man am Mehodennamen (sofern er sinnvoll gewählt ist) ablesen.

das ist leider ein sehr verbreiteter Irrglaube, der immer wieder zu an sich unnötigen Fragen hier im Forum führt. Eine Reihe von Programmierern schauen fahrlässigerweise selbst dann nicht in die Dokumentation der Methode, wenn sie feststellen, dass die Methode nicht tut, was sie erwarten bzw. sie aufgrund des Namens der Methode annehmen. Der Name eine Methode lässt einen viel breiteren Interpretationsspielraum, was genau die Methode tut, als viele wahrhaben wollen.

Der Name der Methode alleine ist sowieso weniger als die halbe Miete. Aber selbst wenn man die gesamte Signatur der Methode betrachtet, also auch den Rückgabetyp und die Parametertypen und -namen, weiß man eben noch lange nicht,* was genau die Methode macht,

  • welche Wertebereiche für Parameter zulässig sind (insbesondere aber nicht nur, ob null erlaubt ist),
  • wie die Parameterwerte zu interpretieren sind (insbesondere für Sonder- oder Grenzwerte),
  • ob der Rückgabewert ein neues oder ein (verändertes) bestehendes Objekt ist (man denke an String.Replace),
  • ob die Methode außer der Rückgabe noch etwas anderes ändert (Seiteneffekt),
  • welche Exceptions sie in welchen Situationen werfen kann,
  • wie sie sich überhaupt im Fehlerfall verhält (also z.B. ob atomar oder nicht),
  • ob bzw. in wieweit die Methode threadsicher ist,
  • ob die Methode nur in einem bestimmten Objektzustand aufgerufen werden darf,
  • ob vorher oder nachher bestimmte andere Methoden aufgerufen werden müssen,
  • und noch so einiges mehr.

Das alles gehört in die API-Dokumentation und ich ärgere mich jedes Mal, wenn diese wichtigen Informationen fehlen.

Entgegen deiner Aussage gehört in die API-Dokumentation auf jeden Fall, WAS die Methode macht. Eben weil der Benutzer der API-Dokumentation - wie eben schon gesagt - den Quellcode nicht kennt und nicht kennen sollte. Insofern ist es hier nicht nur ok, sondern eben sogar erforderlich, dass eine bestimmte Redundanz zwischen API-Dokumentation und Quellcode besteht.

Anders sieht es aus, wenn man über die Kommentare für den Implementierer bzw. Änderer des Quellcodes sprechen (meist innerhalb der Methoden) sprechen. Da ist es durchaus angebracht, das WARUM bzw. die Zusammenhänge in den Vordergrund zu stellen. Das WAS steht ja im Quellcode, den die betreffende Person zusammen mit den Kommentaren direkt vor der Nase hat.

Das ist also eine ganze andere Situation als bei Kommentaren für die API-Dokumentation. Deshalb habe ich schon oben darauf hingewiesen, dass ihr immer dazu schreiben solltet, worüber ihr gerade redet, also ob über // oder über ///.

herbivore

S
211 Beiträge seit 2010
vor 12 Jahren

Selbst mit guter Absicht und Sorgfalt erstellte Kommentare können inhaltlich falsch oder missverständlich formuliert sein und dadurch schaden.

Selbst in mit guter Absicht und Sorgfalt erstellten Kommentare können gerade die Informationen fehlen, die ein späterer Leser mit einem anderen Erfahrungshintergrund benötigt.

Diese 2 Punkte haben aber eigtl nichts mit der Menge der Kommentare zu tun. Weil das kann bei wenigen Kommentaren genauso passieren wie bei sehr vielen auch, weils dann vermutlich am Verfasser liegt.

49.485 Beiträge seit 2005
vor 12 Jahren

Hallo scrabbl,

ich habe nie behauptet, dass sich die(se) Argumente auf die Menge der Kommentare beziehen. Ich habe ganz generell über die Nachteile von Kommentaren gesprochen. Natürlich nicht um vom Kommentieren abzuraten, sondern nur um der von Lynix aufgestellten Behauptung entgegenzutreten, es gäbe keine Nachteile.

herbivore

L
667 Beiträge seit 2004
vor 12 Jahren

Hallo herbivore,

ich kann Deinen Punkten nicht oder nur begrenzt zustimmen.

•Es fängt damit an, dass es (Arbeits-)Zeit kostet, Kommentare zu erstellen.

Einen unkommentierten Fremdcode nachvollziehen zu müssen ist ab einer gewissen Mindestkomplexität sicherlich Zeit- und damit auch Kostenintensiver.

•Dann müssen Kommentare an Codeänderungen angepasst werden, die müssen also aktuell gehalten werden.

Das stimmt natürlich, ist aber kein "Nachteil eines Kommentars". Die Alternative, keine Kommentare zu nutzen ist sicherlich nicht besser als der unbestrittene Fakt, dass Kommentare auch gepflegt werden müssen.

•Das kann vergessen werden und zu Inkonsistenzen führen.

Stimmt, aber von vorneherein keine Kommentare zu machen kann dagegen dazu führen, dass ein Entwickler tage- oder wochenlang versucht einen Code nachzuvollziehen, der mit einem Kommentar sofort klar wäre.

•Wenn die Änderungen nicht vergessen werden, kosten sie erneut Zeit.
•Je mehr und je längere Kommentare existieren, desto mehr Zeit kosten die Aktualisierungen und desto eher übersieht der Änderer notwendige Aktualisierungen.

siehe Punkt 1 - dass es Zeit kostet und gepflegt werden muss ist klar, aber mit dieser Argumentation könnte man auch sagen "Programmieren ist ein Nachteil" oder "Zähne putzen ist ein Nachteil".

•Selbst wenn Kommentare keine überflüssigen Informationen enthalten, können sie den Code auseinander ziehen/reißen und dadurch die Übersichtlichkeit verringern.

Ich bleibe dabei, dass ordentlich formatierte Kommentare einen Code nicht unübersichtlicher machen. Das passiert nur wenn man es gezielt darauf anlegt wie
Winsharp93 es oben in einem Extrembeispiel gezeigt hat.

•Selbst mit guter Absicht und Sorgfalt erstellte Kommentare können inhaltlich falsch oder missverständlich formuliert sein und dadurch schaden.

Diesen Punkt lasse ich bedingt gelten, wobei es auch hier nicht um einen Nachteil des Kommentierens geht, sondern um die Kommunikationsfähigkeit des Mitarbeiters. Dieses Problem besteht bei allen Arbeitsabläufen, bei denen zwei oder mehr Personen miteinander kommunizieren müssen.

•Selbst in mit guter Absicht und Sorgfalt erstellten Kommentare können gerade die Informationen fehlen, die ein späterer Leser mit einem anderen Erfahrungshintergrund benötigt.

Worin liegt dann der Nachteil im Vergleich dazu gleich garkeinen Kommentar zu hinterlegen ?

"It is not wise to be wise" - Sun Tzu

49.485 Beiträge seit 2005
vor 12 Jahren

Hallo Lynix,

du hast mich offensichtlich leider überhaupt nicht verstanden. Du hast geschrieben, dass es keine Nachteile gibt. Ich habe diese aufgezeigt. Ich habe nie behauptet, dass den Nachteilen keine Vorteile gegenüberstehen. Ich habe im Gegenteil sogar gesagt, dass ich ein Befürworter von Kommentaren bin, also finde, dass die Vorteile die Nachteile überwiegen. Trotzdem sollte man vor den Nachteilen nicht die Augen verschließen.

Denn die Vorteile überwiegen die Nachteile nur, wenn man es richtig macht. Schreibt man zu viele Kommentare können die Nachteile genauso überwiegen wie bei zu wenigen Kommentaren. Die Zeitersparnis (Vorteil) für den Leser der Kommentare muss den Zeitaufwand (Nachteil) für das Erstellen der Kommentare überkompensieren, damit die Rechnung aufgeht. Deine These "je mehr, desto besser" ist so pauschal sicher falsch. Anderseits habe ich ja oben durchaus eine Menge Punkte aufgeführt, die sich zu dokumentieren lohnen. Und das alleine sind vermutlich schon deutlich mehr, als üblicherweise dokumentiert wird.

herbivore

L
667 Beiträge seit 2004
vor 12 Jahren

Hallo zusammen,

für mich gehört in einem perfekten Sourcecode jede Code-Zeile, die nicht trivial ist, d.h. in der nicht bloß eine Variableninitialisierung oder eine Wertzuweisung o.Ä. stattfindet, dokumentiert. In diesem Sinne kann man eigentlich garnicht genug Kommentare schreiben, und das Argument, zu viele Kommentare würden einen Sourcecode unübersichtlich machen, sehe ich nicht ein. Das mag vielleicht so sein, wenn man mit notepad.exe programmiert, aber wer tut das heutzutage noch ?

Hinweis von herbivore vor 12 Jahren

Um es abzukürzen: Deine Meinung ist dir unbenommen. Ob sie geteilt wird, muss jeder für sich selbst entscheiden. Für meine Meinung gilt natürlich nichts anderes.

"It is not wise to be wise" - Sun Tzu

A
764 Beiträge seit 2007
vor 12 Jahren

Das artet aber ganz schön in arbeit aus 8o
Das würde ja bedeuten, dass du für jede Codeänderung auch die Kommentare ändern müsstest und wenn du es mal vergisst, oder nicht richtig machst, hast du Fehler drinne.

5.742 Beiträge seit 2007
vor 12 Jahren

Ich finde es in diesem Zusammenhang irgendwie "interessant", dass bei TDD immer gejammert wird, wie hoch doch die Mehraufwände sind und wie mühselig die Wartung der Tests.

Und bei Kommentaren ist der Mehraufwand dann plötzlich kein Thema mehr...
Dabei sind gute Tests auch eine sehr gute Art von Dokumentation.

C
1.214 Beiträge seit 2006
vor 12 Jahren

für mich gehört in einem perfekten Sourcecode jede Code-Zeile, die nicht trivial ist, d.h. in der nicht bloß eine Variableninitialisierung oder eine Wertzuweisung o.Ä. stattfindet, dokumentiert.

Das halte ich für deutlich übertrieben. Je mehr Erfahrung man hat, desto weniger interessieren einen die Kommentare. Und grob geschätzt (und vielleicht übertrieben) 98% vom Source ist meist nun mal mehr oder weniger Boiler Plate Code. Was für die Doku interessant ist, ist die API von den Bibliotheken, und die eigentliche Business Logik, damit man die Abläufe nachvollziehen kann. Und das macht nun mal einen relativ kleinen Anteil am Gesamtcode aus.

C
2.121 Beiträge seit 2010
vor 12 Jahren

Kommentare im Code (-> keine die Methoden oder Felder beschreiben) sind eigentlich nur für Blöcke sinnvoll. Jede Zeile kommentieren halte ich für unsinnig. Das hält nur beim Lesen auf.
Stattdessen ist es sinnvoller wenn längere Abläufe immer wieder mal kommentiert werden und sei es nur um beim Debuggen zu wissen wo man etwa gerade ist.

Gelöschter Account
vor 12 Jahren

Stattdessen ist es sinnvoller wenn längere Abläufe immer wieder mal kommentiert werden und sei es nur um beim Debuggen zu wissen wo man etwa gerade ist.

Hm.. jain. Eine Methode sollte nicht länger als eine Bildschirmseite sein. Bitte zerpflückt das jetzt nicht. ich weiß das es nicht immer geht aber als grober Richtwert fährt man damit sehr gut.

49.485 Beiträge seit 2005
vor 12 Jahren

Hallo chilic,

ich hatte schon weiter oben überlegt, dem in meinen Augen überzogenen Vorschlag, nahezu jede Codezeile zu dokumentieren, den Vorschlag entgehen zu stellen, im Normalfall nur ganze Codeblöcke bzw. Codeabschnitt zu dokumentieren. Allerdings hat mich genau das Gegenargument, das JAck30lena jetzt genannt hat, abgehalten. Denn wenn man einen Codeabschnitt hat, der eigenständig genug ist (hier: um ihn zu dokumentieren), dann gehört der nach der gängigen Lehre in eine eigene Methode.

Allerdings muss ich zugeben, dass ich dazu neige, eine solche Aufteilung in Mini-Methoden zu unterlassen, sondern stattdessen den Code der (längeren) Methode eben durch Kommentare für Codeabschnitte zu strukturieren (siehe z.B. die DoMatch-Methode im mitgelieferten Quelltext von On-the-fly Regex-Tester: Regex-Lab).

herbivore