Code-Doku
-
Wie macht ihr die allseits beliebte Dokumentation zum Code?
Ich denke, viele benutzen höchstens Doxygen.
Aber ist das wirklich so sinnvoll? Ich find es total überflüssig. Ich hab dann hunderte Funktionen, wo die Parameter dazu beschrieben werden.
Aber um wirklich in einem etwas größeren Projekt durchzusteigen brauch ich von hand geschriebene Struktogramme oder meinetwegen auch Texte, die mir die Verknüpfung zwischen den Funktionen und die Abläufe erklären.
Um etwas gut zusammenzufassen muss man eben manche Sachen weglassen und andere ausführlich erklären, so etwas kann nicht die tollste KI erledigen.
Gruß,
alphabetacharly
-
Du kannst mit Doxygen ja Zusammenfassungen erstellen/Unwichtige Stellen auslassen (internal Schalter).
Der Sinn von Doxygen ist ja Dokumentation aktuell zu halten. Eine externe Zusammenfassung/Beschreibung neigt dazu an Aktualität zu verlieren
-
Du kannst ja einen UML-Editor nehmen und Dich dann voll austoben: Struktogramme, Anwendungsfalldiagramme, OCL, Mealy-/Moore-Automaten, Sequenzdiagramme auf Klassenebene, Metaebene I & II, Objektebene, als Packages, als Komponenten, als Klassen...
-
Doxygen hat den unangenehmen Effekt, dass die meisten Programmierer das Bild für das ganz verlieren und damit die Zeit verschwenden ohnehin offensichtliche Parameter zu dokumentieren. Außerdem werden die Informationen immer auf gleiche Weise aufbereitet. Doxygen allein macht keine gute Doku imho!
Aber wie heißt es so schön "Mit Dokumentationen ist es wie mit Sex: Lieber schlechten als gar keinen."
-
Hi,
die einzige Doku die immer aktuell ist ist der Quelltext selber. Also ist das wichtigste, so zu programmieren, daß sich der Quelltext wie eine Doku liest.
Wer außer für reine Schleifenvariablen rudimentäre unverständliche abkürzungen im Code verwendet ist selber Schuld, wenn er hinterher nur noch Bahnhof versteht. Sinnvolle namen für alle Funktionen und Variablen, Klassen... geben ist manchmal ein bisschen mehr Schreibarbeit, aber es lohnt sich.
auch lohnend, heute nicht mehr zu verfrickelt zu programmieren. Moderne compiler optimieren selbst.
Ungarische Notation sehe ich dagegen als Schnickschnack an. Meine IDE (Borland) zeigt mir wenn ich mit der Maus drüber fahre was es ist.
Und letztlich mal an Stroustups Tip denken: Halten sie Kommentare knackig.Gurß Mümmel
-
Im wesentlichen dokumentiere ich auf zwei Arten:
Sobald das Projekt größer wird, schreibe ich einen relativ fließenden Text, der die Datenstruktur und die Funktionalität umreißt, dazu noch bissl über Fehlerbehandlung (wo können im wesentlichen "wichtige" Exceptions auftreten, wie werden sie behandelt).Im Code selber schreibe ich nur wenige Kommentare und zwar dort, wo ich weiß, dass ich nach einiger Zeit nicht mehr durchblicken könnte. Manchmal brauche ich in eigentlich trivial erscheinenden Funktionen doch noch eine Art Mini-Algo, der noch ein paar Spezialfälle o.Ä. abdeckt. Da kommt dann halt 'nen Kommentar in den Code, der erklärt, wieso der Algo da hin muss und was er im Wesentlichen bewirkt. Und wenn eine Funktion länger wird und sich logisch in einige Bereiche einteilen lässt, werden die halt auch gekennzeichnet.
edit: Doxygen finde ich bei Libraries ziemlich sinnvoll, in denen man mal im Browser durch die namespaces oder Header schnüffeln will.
-
die einzige Doku die immer aktuell ist ist der Quelltext selber
Das stimmt nicht...
Wir entwickeln unsere Software komplett modellgetrieben und die Doku für Analyse/Design/Implementierung und Test ist immer aktuell, da wir sie aus dem Modell generieren.Doxygen kann nur als Methoden/ Parameter Dokumentationstool genutzt werden, da es nicht automatisch logisch sinnvolle Klassendiagramme sowie die ganze dynamische Sicht auf das System erstellen kann.
-
rüdiger schrieb:
Doxygen allein macht keine gute Doku imho!
Ich würde sogar sagen, dass man mit Doxygen gar keine Doku macht, eher eine (Programmierer-)Referenz.
-
paddy@work schrieb:
die einzige Doku die immer aktuell ist ist der Quelltext selber
Das stimmt nicht...
Wir entwickeln unsere Software komplett modellgetrieben und die Doku für Analyse/Design/Implementierung und Test ist immer aktuell, da wir sie aus dem Modell generieren.Ist in diesem Fall nicht eben das Modell der Quelltext? Nur halt nicht in Textform?
-
Tim schrieb:
Ich würde sogar sagen, dass man mit Doxygen gar keine Doku macht, eher eine (Programmierer-)Referenz.
it depends. du hast recht, dass sich doxygen dokus häufiger mal eher als beschreibung des quelltextes lesen denn als dokumentation, wie man diesen nutzen soll. aber aus meiner sicht, liefern viele programmierer mit doxygen überhaupt erst eine doku ab.