Dokumenation von Quelltext

[vimix]

Ich mache mir gerade Gedanken darüber wie ich meinen in der Zukunft entstehenden Quelltext dokumentieren soll.
Bisher habe ich die Dokumentation direkt in den Quelltext mittels Javadoc-/Doxygentags geschrieben. Mittlerweile
bin ich jedoch der Meinung, dass das den Quelltext sehr aufbläht. Moderne IDEs kompensieren das zwar sehr gut,
aber naja...
Interessensshalber habe ich gerade in den FreeBSD-Codetree geschaut und gesehen, dass auch so große Projekte
ohne auskommen. (auch wenn derart alter Code heutzutage mit einem anderen Maß gemessen werden muss.)

Jetzt zu den Fragen die ich hier gerne diskutieren will.

Hat eine derartige Dokumentation des Quelltextes innerhalb des selben wirklich Vorteile?
Gibt es alternative Methoden um eine derartige Dokumentation extern zu erzeugen?

[zwergmulch]

Hi, da ist wohl mal wieder einer der tatsächlich seinen Code kommentiert?
Oder vielleicht doch nicht?

Mittlerweile bin ich jedoch der Meinung, dass das den Quelltext sehr aufbläht.

Hast recht, wozu auch Kommentare. Und noch möglichst viel Goto. Sch*** auf die Wartbarkeit.

Hat eine derartige Dokumentation des Quelltextes innerhalb des selben wirklich Vorteile?

Nunja, du hast Kommentare und Dokumentation auf einen Schlag, sprich

• Andere Leute können sich leichter in deinen Quelltext einarbeiten/fertige Funktionen davon nutzen.
• Du arbeitest dich nach einer (längeren) Pause leichter wieder ein.

Gibt es alternative Methoden um eine derartige Dokumentation extern zu erzeugen?

Klar, du kannst per Hand via Notepad, Word oder in HTML die Dokumentation schreiben.
Viel Spaß dabei!

Grüße zwergmulch, der heute wohl seinen ironischen Tag hat. Bitte nicht übel nehmen.

[Jonathan]

Ich finde doxygen eigentlich fast ideal. Es hat schon einige Vorteile, die Dokumentation direkt neben dem Code zu haben, wenn man nicht zwischen programmieren und dokumentieren umschalten muss, macht man da viel eher mal etwas mit. Und auch wenn man fremden Code liest, hilft es einfach, die Dokumentation daneben stehen zu haben. Und man kann natürlich aus den Kommentaren noch schicke Dokumentation in HTML oder so erzeugen.
Solange mir niemand etwas noch besseres zeigt, bin ich von Doxygen auf jeden Fall überzeugt.

[Thoran]

Ich finde Doygen auch super. Aber mann musss natürlich auch sinnvolle Dokumentation dazuschreiben, sonst hilft Doxygen nix.

Bisher habe ich die Dokumentation direkt in den Quelltext mittels Javadoc-/Doxygentags geschrieben. Mittlerweile
bin ich jedoch der Meinung, dass das den Quelltext sehr aufbläht.

Ich halte mich an die Konvention die Funktionen mittels Doxygen nur im Header zu dokumentieren. Damit bleiben die *.cpp Dateien klein mit Ausnahme von direkten Kommentaren zum Verständnis eines Algorithmusteils.

Für Bibliotheken finde ich eine gute Dokumentation unabdingbar. Ob man auf diese Weise das eigenen Programme(im Sinne von *.exe) dokumentieren muss, ist Geschmacksache, aber bestimmt nicht verkehrt.

Thoran

[vimix]

Hast recht, wozu auch Kommentare. Und noch möglichst viel Goto. Sch*** auf die Wartbarkeit.

Bitte nicht die Kommentare mit Javadoctags verwechseln. Ich sage nicht, scheiß auf Kommentare.
Wartbarkeit und Doxygen sollten imho so wenig wie möglich miteinander zu tun haben.
Auf den Sinn und Unsinn von Goto gehe ich hier garnicht ein.

Nunja, du hast Kommentare und Dokumentation auf einen Schlag, sprich

* Andere Leute können sich leichter in deinen Quelltext einarbeiten/fertige Funktionen davon nutzen.
* Du arbeitest dich nach einer (längeren) Pause leichter wieder ein.

Naja, hier liegt oft ein Hund begraben. Wenn man Doxytags benötigt um sich und anderen das Einarbeiten in den Code zu
ermöglichen/erleichtern, dann kann man vieles am eigenen Code verbessern. In den meisten Fällen sind Doxygenkommentare
doch nur Aussagen, welcher der Code selbst über sich treffen sollte.

Klar, du kannst per Hand via Notepad, Word oder in HTML die Dokumentation schreiben.

Kennt niemand gute Alternativen? Andere Wege und Tools?

[qote]
Grüße zwergmulch, der heute wohl seinen ironischen Tag hat. Bitte nicht übel nehmen.[/quote]
Natürlich nehme ich dir nichts übel. Die Ironie ist genau das, auf was ich auch hinaus wollte.

Ich finde doxygen eigentlich fast ideal. Es hat schon einige Vorteile, die Dokumentation direkt neben dem Code zu haben, wenn man nicht zwischen programmieren und dokumentieren umschalten muss, macht man da viel eher mal etwas mit. Und auch wenn man fremden Code liest, hilft es einfach, die Dokumentation daneben stehen zu haben. Und man kann natürlich aus den Kommentaren noch schicke Dokumentation in HTML oder so erzeugen.

Die Frage ist. Wenn man guten Code schreibt, wann muss man in die Doxygendokumentation schaun? Eigentlich nie.
Ich gebe dir recht, wenn ich schlechten Code vor mir habe, bin ich für jede weitere Dokumentation dankbar.

Für Bibliotheken finde ich eine gute Dokumentation unabdingbar. Ob man auf diese Weise das eigenen Programme(im Sinne von *.exe) dokumentieren muss, ist Geschmacksache, aber bestimmt nicht verkehrt.

Ja, ich suche eine möglichst bequeme Möglichkeit, diese Zusatzdoku aus dem Code rauszubekommen.

[zwergmulch]

Bitte nicht die Kommentare mit Javadoctags verwechseln. Ich sage nicht, scheiß auf Kommentare.
Wartbarkeit und Doxygen sollten imho so wenig wie möglich miteinander zu tun haben.
Auf den Sinn und Unsinn von Goto gehe ich hier garnicht ein.

Javadoctags sind imho eine spezielle Art/Syntax von Kommentar, oder etwa nicht.
Und wieso sollten Wartbarkeit und Doxygen nicht viel miteinander zutun haben?
Wie gut auch immer der Code ist, Kommentare (und auch Doc-Kommentare, die ja zusammenfassen sollten was eine Methode/Klasse/etc. leistet)
helfen beim Verständnis. Sicher, wenn man seine Methoden f, g, h usw. nennt braucht man Doxygen,
aber selbst wenn man ihnen verständliche Namen gibt helfen die immmernoch.
Außerdem muss man nicht gleich die (eigentliche) Dokumentation bemühen sondern kann schnell in den Header schauen.

Achja, das "Scheiß auf Kommentare" war Ironie, da es ja imo keinen Grund gibt mit (Doc-)Kommentaren zu geizen (solange sie sinnvoll bleiben).

Naja, hier liegt oft ein Hund begraben. Wenn man Doxytags benötigt um sich und anderen das Einarbeiten in den Code zu
ermöglichen/erleichtern, dann kann man vieles am eigenen Code verbessern. In den meisten Fällen sind Doxygenkommentare
doch nur Aussagen, welcher der Code selbst über sich treffen sollte.

Siehe oben. Außerdem hat man halt gleich automatisch eine HTML-(oder TeX etc.)Dokumentation, wenn man grad nicht in den Code schauen kann.

Ja, ich suche eine möglichst bequeme Möglichkeit, diese Zusatzdoku aus dem Code rauszubekommen.

So etwas ist doch javadoc für Java, wenn ich das richtig verstanden habe.

[Lord Delvin]

Dokumentation sollte eigentlich nur da sein, wo man den eigentlichen Code nicht ansehen kann oder will, also im großen und ganzen in headern von bibliotheken. Ich find doxygen und jml nützlich. Schade dass es sowas wie jml + tools nicht für C++ gibt:-/

// Dokumentation im Code finde ich eigentlich meistens unangebracht, es sei denn um Dinge zu erklären, wenn man tutorialartigen Code schreibt oder wenn man was macht, was nicht intuitiv ist; muss man ja leider manchmal

[grid]

Ich unterscheide jetzt mal zwischen Kommentar und Dokumentation:
- Kommentar ist das, was der/die Entwickler brauchen, um den Sourcecode zu verstehen. Kommentare sind also eine Art kurze private Dokumentation.
- Domkumentation ist das, was Anwender des Codes (z.B. einer API) benutzen oder auch das was ich beim Codereview beilege, damit jemand anderes den Einstieg findet/einen Überblick bekommt.

Soviel zu meiner Definition. Normalerweise finde ich, dass man soetwas nicht zu unterscheiden braucht. Wenn man aber unbedingt die Code-Dateien ohne "überflüssigen" Doku-Balast haben will kann man ja die Dokumentation einer Klasse/Methode in einer Textdatei machen und mit z.B. mit Doxygen(\include <file_path>) an die entsprechenden Stellen verlinken. Somit hätte man eine Unterteilung in die kurzen Kommentare und die Ausführliche Dokumentation.

ALLERDINGS: Ich finde das äußerst unpraktisch und nicht besonders gut zu warten. Denn auch die Dokumentation muss gewartet werden. Es ist schon ziemlich ärgerlich, wenn nach einer Änderung am Code vergessen wurde die Doku zu anzupassen. Ansonsten gilt für mich auch Doku in die Header und Kommentare nur an den Stellen im Code, die nicht intuitiv sind. Spezialfall sind //TODO oder //BUGTICKET Kommentare, über deren Sinn/Unsinn knn man sich streiten. Die sind aber gerade in Teams ziemlich nützlich.

[dronus]

Sobald Funktions/Methoden-Kommentare länger als der Methodencode werden bin ich skeptisch. In der Regel versuche ich dann die Funktionen zu ändern. Der Kommentar kann sowieso nur einen Eindruck vom Wunschverhalten einer Funktion geben und nie exakt die Wirkung beschreiben. Eine Funktion sollte sich so verhalten dass man sie kurz beschreiben kann, wenn man Glück hat verschwindet der Kommentar dann im Funktionsnamen. Z.b. würde ich von getSomething(..) keine Seiteneffekte erwarten. Wird something aufwendig berechnet, nenne ich die Funktion immer computeSomething(..) um auf den Seiteneffekt von Laufzeit/Speicher hinzuweisen. Wenn eine Funktion bei einer Berechnung weitere Resultate als Seiteneffekte erzeugt, sind Kommentare sinnig. So etwas akzeptiere ich allerdings nur dort, wo die zusammenhängenden Resultate aus Performancegründen nötig sind. Ich würde sonst immer versuchen die Funktion in mehrere klar beschreibbare Funktionen zu spalten.

Mittlerweile bin ich ein großer OpenSource-Fan. Ich mache viel mit Java, wo üblicherweise keine Header verwendet werden. Soweit es geht binde ich Fremdcode als Source ein, da ich mich dann nicht auf die Dokumentation verlassen muss sondern den Code selber einsehen kann. Ich würde mich sehr freuen wenn der Code so lesbar wie die Dokumentation wäre. Oft ist die Dokumentation so schlecht dass auch gammeliger Code besser ist

Bei der Programmierung mit C war die Entdeckung von Linux gewaltig. Auf einmal konnte ich ohne große Mühe einen Riesensack Bibliotheken benutzen und jederzeit in den Code sehen wenn mir irgenwas spanisch vorkam. Das ergab einen dramatischen Produktivitätsschub und ich sehe das als Hinweis darauf das Dokumentation dramatisch überbewertet ist!

[kimmi]

Man kann übrigens auch per Doxygen komplette Tutorials und API-Dokumantationen mit allem Pipapo schreiben. Und ich halte Dokumentationen der öffentlichen Schnittstellen mit den Klassen-Contracts für eine sehr wertvolle Dokumentation einer Lib / Applikation. Gerade das Verhalten im Fehlerfall ist für Benutzer interessant und da schreibe ich lieber einen Satz mehr als zu wenig. Schließlich sind offene Flanken potentielle Support-Anfragen, die Benutzer abschrecken oder mir irgendwann Arbeit machen -> schlecht. Und da ich im Job an einem Framework arbeite, konnte ich mir dort schon Arbeit von der Backe halten -> gut.
Bei privaten internen Schnittstellen gehe ich nicht so weit, die Doku massivst aufzublähen und alles mit Beispielen zu untermauern. Ein kurzer Hinweis, was eine Metode macht, reicht mir. Wenn der Methoden- oder Funktions-Name nicht grob erklärt, was das Stück Code macht, versuche ich, das zu optimieren. Kommentare im Code baue ich nur an den Stellen ein, wo es meiner Ansicht nach nicht anders geht ( kurze Erklärung eines komplexes Alogorithmus mit Verweisen zu detailierter Doku zum Beispiel ). Ansonsten versuche ich den Code an sich so weit es geht selbsterklärend zu schreiben.
Ich halte Doxygen für eine gute Sache und das Generieren einer kompletten Doku aus dem Code heraus für besser als Pflegen parallel aufwachsener Dokumente, die meiner Erfahrung nach nie aktuell sind. Allerdings sollte man Doxygen nicht als Referenz-Doku-Generator allein mißbrauchen. So eine generierte Doku hilft niemanden. Wenn man aber mittels Doxygen ein wirklichen Leitpfaden mit Beispielen aufbaut, kann das ein wirklich wichtigen Werkzeug sein.
Und ja, bei Assimp benutze ich ständig die Doxygen-Hilfe.

Gruß Kimmi

[Jonathan]

Natürlich sollte man sinnvolle Funktionsnamen haben, die angesprochene Sache mit dem computeSOmething statt getSomething mach ich z.B. auch und das ist auch um einiges sinnvoller, als nur ein Kommentar mit dem erwarteten Aufwand daneben zu schreiben. Den Namen sieht man schließlich auch überall, wo man die Funktion aufruft, die Dokumentation dagegen viel seltener.
Aber trotzdem sind Doxygen Kommentare toll, ich versuche z.B. zu jeder Klasse einen kurzen Text zu verfassen, wofür genau sie zuständig ist, und wofür eben nicht. Alleine das schreiben dieses Absatzes ist wirklich sinnvoll, weil oft hat man die Ideen zwar grob im Hinterkopf, entdeckt Fehler aber erst, wenn man sie mal ausformuliert. Ich habe schon einige male beim Kommentare schreiben gemerkt, dass ich eigentlich erst noch den Quellcode verbessern muss.
Je mehr Zeit man beim schreiben des Codes verbringt, desto weniger verschwendet man damit, ihn neu zu schreiben.

[kimmi]

Es heißt ja nicht ohne Grund, man dokumentiert private in der Regel für sich selbst. Da findet man durch das Reflektieren des eigenen COdes gern mal einen Schnitzer. Das gepaart mit Integrationstests haben mir schon viele Fehler vor dem Release offenbahrt. Und das allein sorgt schon dafür, daß ich zumindest eine kurze Doku je Methode / Funktion schreibe.

Gruß Kimmi

[NytroX]

Also für mich ist es sehr wichtiig, dass ich in den Kommentaren alles finde was ich zum verstehen des Sources brauche.
Demnach schreibe ich auch ab und zu etwas mehr, wenn nicht klar ist, wie etwas zusammenhängt.
Ausserdem finde ich persönlich immer wichtig zu wissen, WARUM man etwas so programmiert hat, wie es jetzt da steht.

Die Doku der API o.ä. würde ich garnicht in den Source schreiben.
Meiner Meinung nach sind Doxygen und co. meist überflüssig, weil das Ergebnis keine sinnvolle verwendung hat.

Zu einer Doku gehören so viele Teile, dass es im Code einfach keinen Sinn macht, das zu hinterlegen.
Da fängt es an mit einer allgemeinen Übersicht, den verwendeten Konzepten usw. um sich einen groben Überblick zu verschaffen.
Danach geht es dann darum einige Themenbereiche näher zu erläutern, sowie die öffentliche API zu beschreiben.

Als Beispiel nehme ich mal eine DirectX Doku.
Was sehen wir hier alles?

Zunächst kommt mal ein grobes Themenverzeichnis und ein Kapitel namens "Programming Guide".
Darin werden z.B. Konzepte erläutert wie Buffer, Ressourcen, usw.
Weiterhin gibt es generelle Tipps & Tricks zu der Verwendung.
Ich sehe keinen Platz, wo ich das in Doxygen o.ä. sinnvoll platzieren würde.

Der zweite Teil "Reference" besteht dann letztendlich in der Auflistung der Interfaces usw.
Hier könnte man gut mit Doxygen und co. arbeiten.
Aber: nur der offizielle Teil (API) gehört hier rein.
Und wenn ich dann im Source sehe, dass es für die Hälfte der Funktionen Doxygen/Javadoc Tags gibt, und für die andere Hälfte nicht, finde ich das auch nicht wirklich toll.

Tutrials usw. in den Source zu packen ist auch irgendwie Quatsch.


Daher find ich Kommentare im Source und eine externe Doku am besten.
Ein Wiki macht sich da meist ganz gut, da kann man dann auch Links setzen uvm.


Mal ein paar andere Beispiele:

SFML: Sehr schön ist hier das Wiki mit Tutorials.
In die Doxygen Doku schaut man doch eher selten. Schaut euch z.B. mal die Klasse "sf::Clock" im Doxygen dort an. Die einzige wichtige Info da drin ist, dass die "GetElapsedTime"-Methode die Zeit in Sekunden zurückgibt.
Z.B. das "Clock()" der Default Contructor ist, da wäre ich vermutlich noch selbst drauf gekommen, aber den ganzen Text hat ja mal jemand eingetippt.

AssImp:
Wichtig wären hier für mich 4 Sachen:
- Wie lade ich Files?
- Wie sieht die Struktur aus, die AssImp mir letztendlich zur Verfügung stellt?
- Was wird unterstützt (z.B. in welchem Format werden Animationen, usw. mit verarbeitet)?
- Wie füge ich meinen eigenen Loader ein?
Für alles weitere ging vermutlich unnötig viel Zeit drauf (abgesehen von der Website, eine gute Präsentation halte ich für wichtig, dafür Daumen hoch).
PS: Überragende Library übrigends, gibt nichts vergleichbares! Großes Lob an der Stelle, auch im Bezug auf die Wahl der Lizenz ("Frei" bedeutet für mich auch, die Freiheit zu haben, meinen Source NICHT zu veröffentlichen)!


Ganz wichtig finde ich auch noch die Anmerkung, dass die Doku immer mit gepflegt werden muss! Also, je weniger Doku ich habe, umso weniger muss ich pflegen.
Daher gilt für mich: So wenig Doku wie möglich, so viel Doku wie nötig.

Aber das ist alles natürlich nur meine persönliche Meinung, also Danke fürs lesen und lasst euch nicht aufhalten

Gruß, NytroX.

[Chromanoid]

Ich persönlich bin großer fan von dokumentations-systemen wie javadoc oder doxygen. Mit der richtigen IDE wird das ganze während des programmierens im codesense fenster o.ä. kontextabhängig angezeigt. man muss sich einfach mal die java api referenz anschauen. da sieht man wie sinnvoll man javadoc einsetzen kann. insbesondere im team ist so etwas ziemlich sinnvoll, da man nicht immer einfach mal eben den quellcode anschauen kann. dafür liest man sich dann schnell das javadoc zur jew. fremden klasse durch und fertig...

[The_Real_Black]

Erfahrungen mit C# und Assembler (C++, Java, HTML usw...) zeigen mir, dass jede Klasse, jede Methode und im Falle von Assembler jede Zeile kommentiert werden sollte. Was kann der Input sein, was der Returnwert und kann eine Exception geworfen werden. Zusätzlich sollten "Blöcke" kommentiert werden (in C# #region xy) um einen groben Ablauf von Methoden zu zeigen (besonders bei EVA Prinzip). Dazu benötigt eine gute Dokumentation auch eine Klassenübersicht UML, Ablaufdiagramme und Co.