Allgemeine Umfrage: Kommentare schreiben
-
englisch sollte man nur benutzen wenn man englisch kann
-
nö, besser schlechtes englisch als spanisch oder griechisch (oder deutsch, wenn ich nicht deutsch wäre)
-
Kommentare "oberhalb" von Klassen und Funktionen dokumentieren den Vertrag - was (d.h. das was auch bei Implementationsänderungen erhalten bleiben muß)
(1) Für Klassen wird dokumentiert welche Rolle sie spielen, Interaktion mit anderen Klassen usw.
(2) Für Funktionen und Methoden und ihre Parameter wird Funktionalität, sowie nicht offensichtliche / von Coding Standards abweichende Randbedingungen und Fehlerbehandlung dokumentiert.Kommentare innerhalb von Funktionen machen den Ablauf verständlich:
(3) von der Standardlösung abweichende Konstrukte (z.B. die kleinen täglichen Tricks, Optimierungen, nicht offensichtliche notwendige Ausnahmenmbehandlung)
(4) nicht offensichtliche Variablennamen
(5) bei längeren Funktionsrümpfen bzw. komplex verschachtelten Blöcken (leicht hervorgehoben) die GrobstrukturWas "notwendig" und was "trivial" ist, ergibt sich letztendlich aus den Anforderungen des Projekts und den Fähigkeiten der beteiligten Entwickler. Konzepte die nachschlagbar sind würde ich grundsätzlich nicht beschreiben (aber als suchbaren Begriff hervorheben).
-
volkard schrieb:
Power Off schrieb:
Das ist ganz einfach: Im Idealfall (wenn man genug Zeit zum Dokumentieren hat), steht im Header einer ".h"-Datei (bei C++) bzw. ".java"-Datei (bei Java), welche Klassen enthalten sind
ja. genau eine. und die hat genau den namen der datei ohne .cpp oder .hpp.
Das geht solange gut, wie die Anzahl der Klassen sich in einem überschaubaren Rahmen hält. Was noch als "überschaubar" gilt, hängt von den jeweiligen Gegebenheiten ab. Natürlich ist es prinzipiell gut, Klassen in jeweils eine eigenes Modul zu machen.
Wenn man jedoch z.B. viele Klassen hat, die alle derselben Gruppe zuzuordnen sind, sollte man durchaus überlegen, ob man sie nicht doch in dasselbe Modul verfrachtet, damit deren Zweck leichter erkennbar ist.
Außerdem vermeidet das unter Umständen eine Explosion von Dateien, durch die niemand mehr durchblickt. Das fängt meistens so an, daß Überlegungen angestellt werden, die vielen Klassen in mehrere Verzeichnisse aufzuteilen. Wenn die Klassen nun keine Black-Boxes sind, und Referenzen auf andere Klassen haben, oder generell abhängig von anderen Klassen sind, die durch die Verzeichnisschieberei in ganz andere Gefilde verfrachtet wurden, fängt es an, unübersichtlich zu werden.
volkard schrieb:
Power Off schrieb:
, und eine Grobbeschreibung der Klassen
außer natürlich, die klasse ist trivial und es ist schon am namen offensichtlich, was sie macht und was sie ist. mach besser kleine klassen und befolge "ein zweck - eine klasse" und hau die kommentare raus.
Warum sollte man eine Klasse nicht dokumentieren? Gerade bei abstrakten oder viel genutzten Basisklassen sollte man durchaus deren Zweck dokumentieren, auch wenn der Code für den Programmierer noch so simpel aussieht. Jemand, der sich z.B. neu in das Projekt einarbeiten muß, wird es unter Umständen schwer haben, zu begreifen, wofür die Klasse wirklich verwendet wird. Eine Einführung in die Verwendung der Klasse sollte daher in der Dokumentation stehen, sowie eine Liste aller bekannten Ableitungen, so daß sich Projektbeteiligte einen Überblick über die Verwendung der Klasse verschaffen können.
Stell Dir vor, Microsoft hätte z.B. so gehandelt, und einfach gar keine WinAPI Dokumentation gemacht ("guck doch ins Header-File, da steht alles drin -- und nee, Kommentare gibt's keine, ist ja alles offensichtlich!").
volkard schrieb:
Power Off schrieb:
Jedes Attribut und jede Methode wird einzeln dokumentiert.
jaja.
size_t size;//die größe //roflGlaub mir, wenn ich bei Dir Leiter der Qualitätssicherung wäre, wäre ich Dein schlimmster Alptraum!
"size_t size; // die größe" ist kein adäquater Kommentar. Das ist überhaupt kein Kommentar, sondern stellt nur das Offensichtliche fest. Das ist genauo was wie "i++; // erhöht i um 1"
Besser wäre z.B. "size_t size; // Kantenlänge des Würfelraumschiffes in Kilometern" bzw. "i++; // Erhöht den Timer für die Selbstzerstörungssequenz um 1 Sekunde"
Wenigstens einen Satz zu einem Attribut oder einer Methode oder einer Anweisung sollte man schon schreiben.
Es gibt immer Leute, die den Code, den jemand anders geschrieben hat, verstehen müssen. Sonst wandert der Code unter Umständen bei einem Wechsel des Teams mehr oder weniger unbesehen im Mülleimer.
volkard schrieb:
Power Off schrieb:
Auch dort sollte man alles dokumentieren: Wofür das Element eingesetzt wird, wie es funktioniert, was es macht, wovon es abhängig ist, usw.
wir leben echt in verschiedenen welten.
Da magst Du vollkommen Recht haben. Aber gib doch zu: Auch Du liest gelegentlich die Dokumentation irgendeiner Library, die Du verwendest. Stell Dir vor, es gäbe keine Doku. Was würdest Du dann machen? Richtig, alles selber schreiben.
Das führt uns zum Hauptproblem fehlender Dokumentation: Code wird innerhalb eines Projektes mehrfach neu geschrieben, weil keine ausreichende Dokumentation für den bestehenden Code vorhanden ist.
volkard schrieb:
Power Off schrieb:
Programme, wie "javadoc" z.B. erlauben es, aus dem Programmtext die eingebetteten Kommentare herauszuziehen und z.B. in HTML zu konvertieren. Je umfangreicher und detaillierter die Informationen sind, desto besser.
was hat man davon?
Dokumentation, die jeder Lesen kann, der zumindest der Bedienung eines Webbrowsers mächtig ist.
Solche Dokumentation kann z.B. anderen Entwicklern, oder auch Entscheidern, die über die Qualität oder die Verwendung des Codes urteilen müssen, helfen, eine Entscheidung zu treffen.
Gute Dokumentation = höhere Rate von Code-Reuse, sowie geringere Fehlerquote, und damit niedrigere Entwicklungskosten.
Stichwort: Einmal entwickeln, mehrfach verwenden, anstatt einmal entwickeln und dann ab in die Rundablage.
Viele Firmen gehen Pleite, weil sie die Ressourcen, das Software-Fundament, das ihre Entwickler geschaffen haben, nicht in ausreichendem Maß wiederverwenden können, und daher die Neuentwicklung von Code durchführen, der eigentlich hätte wiederverwendet werden können. Kosten steigen, die Schulden der Firma auch, Angestellte werden entlassen, und schließlich macht die Firma dicht, bloß weil die Entwickler zu faul waren, ihren Code anständig zu dokumentieren.
Ähnliches gilt für Open-Source-Projekte: Wenn potentielle Mitentwickler Schwierigkeiten haben, den Code zu verstehen, machen sie nicht (mehr) mit, und das Projekt kann im Sande verlaufen.
Wenn aber z.B. ein Entwicklungsleiter sagt, "Schreibt keine Kommentare, das kostet bloß Zeit", dann ist er wirklich selber schuld.
-
Die Wahrheit liegt wie immer in der Mitte. Volkard hat zwar vom Prinzip her Recht, nämlich dass auch ohne Dokumentation immer klar sein soll, was welcher Code macht. Das geht aber nicht so weit, dass man nicht einen kurzen und prägnanten Satz über neue Methoden platzieren kann. Der kostet auch dem Enwickler nicht viel Zeit und hilft, seine Gedanken zu ordnen.
Dein Pingeligkeit auf der anderen Seite ist ebenfalls völlig unangebracht.
Auch dort sollte man alles dokumentieren: Wofür das Element eingesetzt wird, wie es funktioniert, was es macht, wovon es abhängig ist, usw.
Jedes Attribut und jede Methode wird einzeln dokumentiert.
Tragen nur dazu bei, schlechten Code mit komplizierten Beziehungen und unklarer Bedienung zu belassen, anstatt ihn noch verständlicher zu machen, nach dem Motto "also mit den 2 Seiten Doku wird wohl jeder kapieren, was das macht". Völlig sinnlose Zeitverschwendung, einen Preis kriegst du dafür nicht. Technische Daten sind interessant, ist die Sortierfunktion stable, was hat sie im worst- best- und average case für Laufzeiten? Dinge, die man in einem Satz sagen kann und wenn sie die Parameter sort(T[], Comparer<T>) muss ich nicht dazu schreiben, was wofür verwendet wird.
Der Grad der benötigten Dokumentation hängt von der Öffentlichkeit ab. Eine Lib, die ich in 10 Projekten verwende, werde ich besonders sorgfältig dokumentieren, eine private Methode in einer 20fach privat genesteten Klasse ist mir egal.
-
Außerdem vermeidet das unter Umständen eine Explosion von Dateien, durch die niemand mehr durchblickt.
im gegenteil. wenn du hin und wieder mehrere klassen in eine datei steckst, dann wird es durch mehr dateien schlimmer. man weiß nir genau, wo was ist. und je mehr dateien, desto länger dauert die suche. wenn du immer eine datei pro klasse hast, ist die dateienanzahl egal. man hat immer O(1) als suchzeit.
Das fängt meistens so an, daß Überlegungen angestellt werden, die vielen Klassen in mehrere Verzeichnisse aufzuteilen. Wenn die Klassen nun keine Black-Boxes sind, und Referenzen auf andere Klassen haben, oder generell abhängig von anderen Klassen sind, die durch die Verzeichnisschieberei in ganz andere Gefilde verfrachtet wurden, fängt es an, unübersichtlich zu werden.
Stell Dir vor, Microsoft hätte z.B. so gehandelt, und einfach gar keine WinAPI Dokumentation gemacht ("guck doch ins Header-File, da steht alles drin -- und nee, Kommentare gibt's keine, ist ja alles offensichtlich!").
CreateFile hat aber auch 6 parameter und kann files, pipes und viele andere sachen offnen oder erzeugen. klar muß so ein monster dokumentiert werden.
Glaub mir, wenn ich bei Dir Leiter der Qualitätssicherung wäre, wäre ich Dein schlimmster Alptraum!
kaum. ich würde die firma verlassen. oder du.
Besser wäre z.B. "size_t size; // Kantenlänge des Würfelraumschiffes in Kilometern" bzw. "i++; // Erhöht den Timer für die Selbstzerstörungssequenz um 1 Sekunde"
ist doch ebenso müllig.
Wenigstens einen Satz zu einem Attribut oder einer Methode oder einer Anweisung sollte man schon schreiben.
pro anweisung ein satz? naja. das kann doch nur ok sein, wenn du davon ausgehst, daß der leser überhaupt kein c++ kann.
Es gibt immer Leute, die den Code, den jemand anders geschrieben hat, verstehen müssen.
aber überkommentierung macht doch gar nicht verständlicher.
Da magst Du vollkommen Recht haben. Aber gib doch zu: Auch Du liest gelegentlich die Dokumentation irgendeiner Library, die Du verwendest. Stell Dir vor, es gäbe keine Doku. Was würdest Du dann machen? Richtig, alles selber schreiben.
ups. ich schreibe alles selber. das liegt aber nicht an der doku der großen libs, die durchaus vorhanden ist.
Das führt uns zum Hauptproblem fehlender Dokumentation: Code wird innerhalb eines Projektes mehrfach neu geschrieben, weil keine ausreichende Dokumentation für den bestehenden Code vorhanden ist.
nein. nicht wegen der doku, sondern weil man dem fremden code nicht vertraut. weil das andere team keinen schönen code baut, sondern häßlichen code kommentiert. weil unschöner code auch viel eher fehlerhafter code ist als schöner code. weil unschöner code beim fund eines fehlers nicht repariert werden kann.
Viele Firmen gehen Pleite, weil sie die Ressourcen, das Software-Fundament, das ihre Entwickler geschaffen haben, nicht in ausreichendem Maß wiederverwenden können, und daher die Neuentwicklung von Code durchführen, der eigentlich hätte wiederverwendet werden können. Kosten steigen, die Schulden der Firma auch, Angestellte werden entlassen, und schließlich macht die Firma dicht, bloß weil die Entwickler zu faul waren, ihren Code anständig zu dokumentieren.
glaube nicht, daß der hauptgrund ist, daß es weniger kommentarzeilen als befehle gab.
Wenn aber z.B. ein Entwicklungsleiter sagt, "Schreibt keine Kommentare, das kostet bloß Zeit", dann ist er wirklich selber schuld.
klar. das zeit-argument darf nie benutzt werden, um kommentare zu sparen. und schlechter code muss natürlich auch kommentiert werden. guter code braucht keine (kaum) kommentare. tut mir leid, daß du sowas noch nie gesehen hast. aber den gibts. ich meide kommentare, weil sie nix bringen. gar nix zur deutlichkeit beitragen. das einzige gute an kommentaren ist, daß man sie setzen *kann*. und immer, wenn man lust hat, ne zeile zu kommentieren, sollte man vorher versuchen, stattdessen den code zu retten. das geht in 99% der fälle. und deswegen gibt's am ende auch so wenige stellen, wo kommentare noch zu dulden sind.
wir gehen von ganz anderen codern aus. hast da 20 abiturienten an ihrem ersten projekt sitzen (dein stil ist da gut)? oder eher 20 dieser template-köpfe, die sich schon jahrelang mit komplizierten sachen (und damit meine ich nicht, nen komplizierten farbverlauf machen, indem man wenig rechnet und viel in der api-doku blätter) beschäftigen (da ist wohl eher mein stil gut).
oder ne mischung (da hängt's von der mischung ab).
-
Power Off schrieb:
Aber gib doch zu: Auch Du liest gelegentlich die Dokumentation irgendeiner Library, die Du verwendest. Stell Dir vor, es gäbe keine Doku. Was würdest Du dann machen? Richtig, alles selber schreiben.
naja, man macht oft den fehler, jede einzelne funktion zu dokumentieren, statt die konzepte zu erklären.
das ganze .begin() und .end() in der stl verdient keinen kommentar. aber das konzept mit den sequenzen muß wo erläutert werden. am besten durch ein tutorial, das man zu seinem code stellt. hab ich das erste mal wohl 1997 so gemacht. waren ein paar klassen mit vielen templates, die netteren zugriff auf odbc-datenbanken gestattete. viel netteren zugriff. und schnell. wo ein kommentar angebracht war, hab ich den gesetzt. und noch an vielen stellen, wo keiner angebracht war. aber wirklich verständlich wurde die lib, indem ich auf ein paar seiten mal vorgemacht hab, wie es aussehen soll, wenn man mit der lib daten liest und schreibt.
naja, zu c++ muß man vorher meyers, stroustrup, sutters und alexandrescu lesen. und die dort genannten konzepte können als allgemeingut angenommen werden und bedürfen nicht mehr zwingend eines kommentars. bleiben zum kommentieren noch die eigenerfindungen übrig. und davon gibts nicht viele.
-
Ich kommentiere relativ wenig, statt dessen erstelle ich eine extensive Dokumentation des Quellkodes, bei der das Grundkonzept, den Datenfluss, jede Klasse mit ihren Membern und die einzeln Mehtoden erlaeutert werden. Es geht dabei weniger um die Dokumentation einer einzeln Zeile (guter Code sollte fast immer auf den ersten Blick klar sein), als vielmehr zu zeigen, wie sich diese Methode oder Klasse im Gesamtkonzept verhaelt und welche Funktion hierbei hat. Das wirklich Wichtige sind dann schliesslich die Cross-Referenzen.
-
MBCS-CITP schrieb:
Das wirklich Wichtige sind dann schliesslich die Cross-Referenzen.
welchen technischen nährwert haben die?
-
Schnellere Navigation als in der IDE.
Komplexere Konzepte müssen oft mit mehreren Klassen / Entities modelliert werden. Um sich dort einen Überblick zu verschaffen, ist die "externe" docu sehr angenehm.
-
peterchen schrieb:
Schnellere Navigation als in der IDE.
Komplexere Konzepte müssen oft mit mehreren Klassen / Entities modelliert werden. Um sich dort einen Überblick zu verschaffen, ist die "externe" docu sehr angenehm.das erklärt keineswegs den satz "Das wirklich Wichtige sind dann schliesslich die Cross-Referenzen."
der satz klingt danach, als sei das voll wichtig, viel wichtiger als die beschreibung der konzepte oder doku im quelltext.
-
vielleicht "Das wirklich Wichtige an einer externen Dokumentation" ?
-
peterchen schrieb:
Schnellere Navigation als in der IDE.
Komplexere Konzepte müssen oft mit mehreren Klassen / Entities modelliert werden. Um sich dort einen Überblick zu verschaffen, ist die "externe" docu sehr angenehm.
Ich finde eine externe Doku äußerst unangenehm. Und inwiefern das schneller sein soll, ist mir auch ein Rätsel. Eine IDE die mir die Doku als Tooltip anzeigt und auch noch "see also: fooBar()" anbietet, ist das schnellste, was ich mir vorstellen kann. Ideal ist sowas wie Javadoc oder Doxygen, wo ich es in der IDE sehen kann wenn ich programmiere und extern sehen kann, wenn ich gerade nicht programmiere.
-
Ich denke auch, daß die externe Doku aus dem Quellcode kommen muß (sonst pflegt es keiner). Nur die Crosslinks gibt es halt nicht innerhalb der IDE.
(Mit dem Tooltip kommt man einen Schritt weiter - aber z.B. nicht eine Ebene rauf, oder einen zweiten Schritt)
-
Definiere mal bitte genau "Crosslinks". Ich bin mir ziemlich sicher, dass z.B. Eclipse für Java alles kann, was du dir wünscht.