Hi,

ich muß gestehen ich habe noch nie eine doku zu einem Source code von mir geschrieben und bin daher in dem Thema völlig unbedarft...

Allerdings würde ich jetzt das ganze gern mal anfangen, nicht unbedingt weil ich eine doku für den code jetzt unbedingt brauche.. sondern eher weil ich ein paar dinge habe die ich mir gern irgendwo notieren möchte (spezielle flag-combis etc).. Und wenn ich schon dabei bin kann ich auch direkt ne kleine doku zum code draus machen.. schadet sicher nichts

So, nun gibt es da ja diverse tools für welche aus dem Source Code automatisch die Hilfe erzeugen.
ABER: Was ich definitiv nicht möchte ist, das ich vor jeder funktion nen riesen Kommentar block stehen habe etc.. es gibt nichts nervigeres und unübersichtlicheres als das finde ich.

Deswegen.. gibt es irgendein Tool, welches die dateien durch parsed, alle funktionen etc raussammelt, ordentlich strukturiert auflistet und mir dann die möglichkeit gibt AUSSERHALB meines codes die doku dafür zu schreiben?

Also so das mein source von der doku völlig unangetastet bleibt.

Gibt's da was?

Aya~

Das ist eigentlich das beste was man tun kann. Wenn dein Code mehr als einige wenige Zeilen Kommentar benötigt, solltest du mal deine Implementierung überdenken. Code sollte eigentlich so gut wie selbst erklärend sein.
Ich benutze Doxygen, Javadoc & Co eigentlich immer.

_________________
Yeah!

Hm, ich schreib mindestens einen Kommentar über jeder Funktionsdeklaration im JDoc-Stil.


Damit können so ca alle Doku-Generierungstools was anfangen. In Java direkt über der Funktion halt und in C/C++ über der Deklaration in der .h-Datei (Da stört es dann auch nicht im eigentlichen Source ).

Somit kann Eclipse auch sofort ne Hilfe anzeigen beim Funktionsaufruf mit Ctrl+Space (Java und C/C++ mit Eclipse CDT).

Na ja, mein Code braucht nicht mehr als einige winzige zeilen kommentar. Sondern garkeine!
Alle meine funktionen sind in der Regel absolut selbst erklärend!

Es gibt lediglich 2 teile wo ich mir gern eine kleine doku zu machen möchte - das wären zum einen der Freetype Standalone Renderer den ich benutze und zum anderen eine doku zu der RegExp-Library die ich nun nutze.. also die ganzen RegExp ausdrücke etc.

Im grunde geht es mir aber auch nicht unbedingt darum eine doku zu schreiben, das ist im grunde echt relativ überflüssig..
(bei der funktion setColor(float r, float g, float b); ist es ziemlich eindeutig was sie macht und wofür die parameter stehen..

Aber ich möchte gern halt eine übersicht über alles im gut strukturierten HTML Format haben, wo ich eben - wenn nötig hier und da doch mal ein paar kleine randbemerkungen machen kann.

Und die 7-zeilen header die Philip da macht sind mir eindeutig zu viel - da verzichte ich dann lieber komplett auf die doku

Aya~

Ich hab bisher meinen Code einfach mit OpenOffice dokumentiert, so dass man in einer Gliederung die einzelnen Units,Klassen und Methoden wieder findet und so schnell durchblättern kann um die Besonderheiten dieser Funktionen zu finden.
Ein hübsch gestaltetes, echt gedrucktes Buch, mit Inhaltsverzeichnis und Index, hat doch einfach viel mehr Charme als eine typische F1-Hilfe.
Allerdings bin ich selbst noch auf der Suche nach einem frei Verwendbarem Tool, mit dem man UML-konforme Diagramme erstellen kann, ohne Sprachabhängigkeit und automatische Codegenerierung.
Diese Vorraussetzung mag zwar etwas seltsam klingen, aber ich schreibe meinen Code lieber komplett von Hand und will die Diagramme häufig zusammenstellen, bevor ich Code schreibe.
Die UML-Diagramme sollen mir beim Schreiben einen Überblick geben, was wie zusammen hängt und ich ggf. streichen kann, wenn ich es schon abgearbeitet hab. Auf Papier will ich das deshalb haben, weil ich oft mit Kugelschreiber oder Rotstift Fehler und Änderungen markiere, das geht meine Meinung nach schneller und intuitiver als mit einem Programm. Änderungen mach ich dann anhand der Markierung in der alten Vorlage in einem Rutsch.

Gibts da sowas? Am besten mit Export nach *.pdf, oder von Adobe unterstützte Vektor-formate.

Edit: entschuldigt, dass ich etwas vom Thema abschweife, aber ne Software Doku ist für mich halt etwas mehr, als nur ne Kommentarzeile...

_________________
Klar Soweit?

Hab mir grad mal Doxygen angeschaut.. das gefällt mir von der übersicht her schon aufjedenfall ganz gut.
Nur die möglichkeit ausserhalb des codes zu dokumentieren fehlt halt leider..

Aber gut, prinzipiell auch nicht so tragisch.. würde ja eh nix groß dokumentieren xD
Mir geht es halt in erster linie um die übersicht im HTML format.

Aber falls sich hier wer mit Doxygen auskennt, 2 fragen hätte ich kurz:

1) Kann ichda in die übersicht eigene HTML seiten mit einbauen..? Also klar, ich kann den source von den generierten HTML files anpassen, aber das wäre dann ja jedesmal futsch wenn ich es neu generiere..

2) Ich habe bei mir ALLES in einem namespace.. in der doxygen doku steht jetzt vor jeder klasse etc mein namespace.. bekomm ich den irgendwie weg? Ich mein, ist ja eh alles der gleiche :p

Aya~

Ich benutze ausschließlich javadoc und klappe die Javadockommentare standartmässig ein. So kann auch eine mehrzeilige Doku auf eine Zeile gekürzt sein. Das reicht mir völlig

Wieso stört dich das dokumentieren im Code denn so sehr? Im Idealfall sieht man die Kommentarzeile im Editor nie bzw. auf eine einzelne reduziert. Wenn man sich die Javadoc mit ihren teils 50 Zeilen Doku pro Klasse und länger anschaut ist man glücklich CodeFolding aktiviert zu haben.

Extern Kommentare zu schreiben halte ich für das schlimmste was man machen kann, denn die dann aktuell zu halten ist immer Extraarbeit die man sich selbst nur ungern zumuten mag. Ich schreib meine Kommentare auch lieber im Code direkt rein, denn die eine Zeile die in aller Regel zugeklappt ist stört beim arbeiten nicht.

_________________
(\__/)
(='.'=)
(")_(")

Ich seh das wie EvilDevil.
Code und Doku zu trennen ist ein massiver Rückschritt da man mit nahezu 100%er Sicherheit garantieren kann, dass nach einigen Änderungszyklen beide nichts mehr miteinander zu tun haben - inhaltlich.

Moderne IDEs bieten das Folding von Kommentaren an. Noch wichtiger finde ich die InEditor-Hilfe, wo einem z.B. Eclipse die Javadoc Doku zu einer Funktion anzeigt, wenn man mit der Maus drauf zeigt.

Da dein Code außerdem so selbsterklärend ist, würde es ja reichen diese eine komplizierte Klasse durchzudokumentieren und nur dafür eine Doku zu generieren.

Zu Doxygen kann ich außerdem noch graphviz empfehlen (Auch der Java-Fraktion). Dort kann man sich auch Aufrufgraphen erzeugen lassen und solche Sachen...

_________________
Blog: kevin-fleischer.de und fbaingermany.com

Inline Doku halte ich für die bessere wahl und du kannst diese am ende eines Funktionskopfes packen oder eine Zeile darüber.
Mehrzeilige Kommentare oder diese Default Kommentarblöcke von Javadoc und Doxygen sind völlig übertrieben und machen den Code wirklich unübersichtlich.

Wenn du die Doku wirklich auslagern willst kannst du das mit Doxygen machen, leider weiß ich nicht mehr wie der Mechanismus aussieht. Ich glaub das war nur eine Includeanweisung aber es geht auf jedenfall. Ich würde aber davon abraten es auslagern, denn es gibt Fälle wo du dir nur ins eigene Fleisch schneidest.

Exceptions werfen ist ne feine sache und wenn der Debugger dich dann zu der entsprechende Stelle bringt, dann kannst du in vielen Fällen schon durch Kommentare die ganze Fehlersuche abkürzen.

_________________
"Wer die Freiheit aufgibt um Sicherheit zu gewinnen, der wird am Ende beides verlieren"
Benjamin Franklin

Projekte: https://github.com/tak2004

Genau das ist das Problem: Falsche Kommentare sind nicht nur wenig hilfreich sondern sogar gefährlich. Aus diesem Grund müssen Kommentar und Implementierung IMMER übereinstimmen. Und das geht am einfachsten, wenn sich alles an der gleichen Stelle befindet.

Was das einbinden von externer Doku angeht...ich denke mal die Optionen EXAMPLE_* und IMAGE_PATH sowie die Kommandos \include und \image sind das was du suchst. Hab ich aber noch nicht selbst benutzt.


Naja, ganz ohne Kommentar ist vielleicht etwas übertrieben. Wenn du dein Projekt in einem Jahr nochmal anschaust ist es vielleicht ganz hilfreich wenigstens zu jeder Klasse und den wichtigsten Methoden ein, zwei Sätze zu haben. Das gilt natürlich insbesondere wenn du den Code veröffentlichen möchtest und andere Leute mit deinem Code zurechtkommen sollen.

_________________
Yeah!

Es geht auch um mehr als nur die Funktionen + parameter zu erklären (was für Fremde die den Code lesen das wichtigste ist).
Vielfach geht es auch darum Architekturentscheidungen, Funktionsvorraussetzungen (Reihenfolgen) etc. zu beschreiben.

Es kostet einfach viel zuviel Zeit 1h lang zu suchen und herauszufinden, dass vor aufruf von doABC() unbedingt ein doXYZ() kommen muss, weil darin etwas initialisiert wird, was bei ABC gebraucht wird.

_________________
Blog: kevin-fleischer.de und fbaingermany.com

Diese Aussage kann in einer Anleitung für schlecht dokumentierten Code stehen... und bekanntlich ist nicht dokumentierter Code nicht existierender Code... Eine Funktion "sayHelloWorld" ist aussagekräftig... alles darüber hinaus Bedarf einer Dokumentation. Als Erzeuger hat man zwar stets einen Heimvorteil, allerdings in einem wirklich großen Projekt Bedarf es nur wenige Woche, wo zumindest eine bestimmte Unsicherheit mit dem Code aufkommt. Insbesondere eben, wenn man noch im Team arbeitet. Ein guter Source Code enthält mehr Kommentare als eigentlichen Code. Über Methoden, Klassen und Konstanten stehen ausführliche Kommentare, logische Folgeschritte im Code werden zusätzlich mit min. einem Einzeiler kommentiert, so dass eine dritte Person durch das lesen der Kommentare einen groben Eindruck erhält, was dort eigentlich los ist. Jemand der nicht ausführliche Kommentare schreibt hat vermutlich noch nie an einem riesigen Projekt Dritter gesessen und diese deswegen verflucht... danach muss man sich nicht einmal mehr dazu zwingen

Und ja, beim Design by Contract das Flash beschreibt sollte die Schnittstelle selbst sogar noch ausführlicher beschrieben werden...

_________________
"Light travels faster than sound. This is why some people appear bright, before you can hear them speak..."

Ich stimme Dir zu. Überhaupt wenn der Code ein wenig komplizierter wird, hat man sellber schon wenige Tage später Schwierigkeiten, genau festzustellen, was zum Teufel man da gemacht hat. Ich versuche grade, einen linearen Solver mit Pascal zu schreiben und die Methode der konjugierten Gradienten in den Griff zu kriegen. Das Zeugs ist so unanschaulich, dass es mal einen Artikel im Web drüber gegeben hat, dessen Titel ungefähr so lautete: "Warum man 50 Seiten lesen muss, um 10 Zeilen Code zu verstehen." Ohne Doku ist man hier völlig aufgeschmissen.

Aus diesem Grund wird OpenSouce - je komplizierter der Source Code wird - gradiell in Closed Source übergehen, OBWOHL man es jederzeit runterladen und ansehen kann, denn mit der Dokumentation hapert es meistens.

Hi,

mhh da scheine ich mich - wie ich mal wieder feststellen muß - wohl von 99% aller anderen programmierenden Menschen zu unterscheiden was das anbelangt.

Ich habe schon öffters Software im Team geschrieben, bzw anderen meinen Code gegeben um damit zu arbeiten.
Leute die der Programmiersprache mächtig sind hatten nie große Probleme sich in den Code rein zu finden, obwohl er nicht kommentiert ist.

Eine Grundvorraussetzung dafür ist allerdings natürlich das man sich mit der Materie auskennt.. wenn ich kein OpenGL kann und soll mich an einen OpenGL Code von jemandem anderen dransetzen bin ich auch aufgeschmissen - da helfen kommentare zwar dann drüber hinweg ein wenig, aber na ja.. das ist ja auch nicht der sinn der sache.


Wenn ich fremd-source bekomme der über mehr als ein paar Zeilen hinaus geht, an dem ich irgendwas machen soll ist es in der regel das erste was ich tue, die Kommentare alle restlos zu löschen und den Code gescheit zu formatieren. Dannach habe ich normalerweise keinerlei Probleme den Code zu verstehen und zu verändern.

Das scheint sowieso mich von anderen zu unterscheiden... mein Code ist komplett anders Strukturiert als alles was ich immer in OpenSource programmen etc sehe.. bei denen blicke ich halt auch erst duch wenn ich es mir so umformatiere wie ich es gewohnt bin.


Und, zum Thema selbst in den Code wieder reinfinden... das mag eine komische gabe sein die ich da habe, aber ich habe auch nach 3 Jahren keinerlei probleme mich auf anhieb in meinem alten Code wieder einzufinden... das habe ich auch schon öffters mal machen müßen.

z.B. habe ich anfang 2007 für eine Firma eine recht umfangreiche Video-Convertier-Software geschrieben.. jetzt vor nem monat etwa wollten sie noch ein paar kleine änderungen an den Overlays die in die Videos gepackt werden. Und obwohl der Code keine einzige kommentar zeile beinhaltet und ich ih nseit anfang 2007 nichtmehr angeschaut habe, war es eine sache von ein paar Minuten..

A) weil ich mich halt in den Code sehr schnell einlesen kann, und B) wenn es mein eigener Code ist den ich vor X-Jahren geschrieben habe, weiß ich auch nach 5 Jahren noch genau was ich wie warum gemacht habe.. das ist - warum auch immer - tief in meinem Kopf verankert.


Klingt jetzt evtl etwas.. mhh.. weiß nich, komisch..
Aber ich hatte nicht schonwieder lust auf eine ewig lange diskussion darüber ob Kommentar jetzt wichtig sind oder nicht, wollte einfach meinen Standpunkt klarmachen und erklären warum für mich Kommentare überflüssig sind.

Aya~