Allgemeine Umfrage: Kommentare schreiben
-
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.