spieleprogrammierer.de - Forum und Wiki zur Spieleprogrammierung und Spieleentwicklung

Lies dir doch als Beispiel Bibliotheksdokumentationen durch, z.B. die von SFML.

Zitat

So kommt es vor, dass mir die Dokumentation wie eine (sinnlose) Doppelung der Signatur erscheint

Wenn du das erkennst, wieso machst du es dann? Wenn die Funktionsparameter aus der Signatur klar sind, brauchst du sie ja nicht nochmals zu dokumentieren. Manchmal reicht eben eine Beschreibung in einem Satz.

Wie ich damit umgehe?
Wenn der Code nur zur privaten Verwendung ist, dokumentiere ich eigentlich nur "Gotchas", Schnittstellen (d.h. abstrakte Basisklassen) und wenige andere Dinge die nicht aus dem Code hervorgehen. Z.B.:

Zitat von »bwbg«

Wie händelt Ihr das? Welche Reiszwecke muss man sich in den Hintern jagen, damit man ordentlich dokumentiert. Lesestoff, Referenzen und allgemeine Ratschläge nehme ich gerne entgegen.

Ich möchte darauf hinweisen, dass hier primär Programmierer (bzw. Softwareentwickler) unterwegs sind, dem entsprechend dürftest du, was das Schreiben einer Dokumentation angeht, wohl eher fehl am Platze sein!
Aber mal Spaß bei Seite: Bei einer Dokumentation kommt es nicht darauf an, wie gut sich die entsprechende Person artikulieren kann, da der Zweck der Dokumentation das dokumentieren der Funktionalität und in gewissem Maße der Implementierung darstellt. Sie muss also nicht hübsch klingen, solange sie verstanden wird. Das Problem dabei ist jedoch, dass die Person, die etwas implementiert hat, diese Implementierung i. d. R. so gut wie die eigene Westentasche kennt und daher auch eine Dokumentation grundsätzlich immer für unnötig hält, da doch alles klar ist. Spätestens wenn dann jemand anderes sich den Code anschaut, dürfte oft genug auffallen, dass es das eben nicht ist.
Ich für meinen Teil muss zugeben, dass ich in Sachen Dokumentation nicht unbedingt der vorbildlichste Entwickler bin. Bei meinen privaten Projekten dokumentiere ich bis auf sehr wenige Ausnahmefälle gar nichts und auf Arbeit wird die Dokumentation nachgepflegt, sollte die entsprechende Funktionalität implementiert sein... vielleicht...

Wenn man mit anderen an einem Projekt arbeitet oder wenn man vor hat, anderen den geschriebenen Code zugänglich zu machen, dann sollte man auch eine entsprechende Dokumentation pflegen. Ich denke, dass es in dem Zusammenhang sinnvoll ist, möglichst für jede Klasse und (öffentliche) Methode zu dokumentieren, was diese macht und ggf. auch wofür diese da ist, also welches Problem sie lösen soll. Wie umfangreich die Code-Doku sein sollte, ist in gewissem Maße Geschmackssache bzw. eine Abwägung aus Aufwand und Nutzen. Welche Sachverhalte so offensichtlich sind, dass sie gar nicht dokumentiert werden müssen, kann auch unterschiedlich wahrgenommen werden, zumal, wie bereits erwähnt, der Ersteller vieles für wesentlich offensichtlicher hält als jemand anderes. Auch das Maß an Erfahrung kann in dem Zusammenhang eine Rolle spielen.
Wenn man ausschließlich alleine an einem Projekt arbeitet, kann es sich ebenfalls lohnen, diverse Dinge zu dokumentieren, damit man auch später noch weiß, warum man etwas so gemacht hat, wie man es gemacht hat oder damit man nicht ggf. später Fehler macht, die man sonst nicht begangen hätte. In meinem Action Adventure ist es beispielsweise so, dass ich ziemlich viel mit Locks arbeiten muss, um Threadsicherheit zu erlangen, da die Skripte parallelisiert ausgeführt werden. Mal abgehesen davon, dass mein Action Adventure diese stellenweise noch nicht besitzt, habe ich eine Stelle, an der ich 2 Listen habe, die für die Bewegungen der Charaktere verwendet werden. In die erste Liste werden die Charaktere eingefügt, wenn ein skript sagt, dass sich der Charakter bewegen soll und die 2. besitzt die aktuell durchzuführenden Bewegungen. Würde ich an nur einer einzigen Stelle nicht darauf achten und die Locks in falscher Reihenfolge setzen, hätte ich eine potenzielle Stelle für einen Deadlock. Unter Berücksichtigung dieser Tatsache, hatte ich ausnahmsweise auch mal sofort ein bisschen was dazu geschrieben.

Also ich dokumentiere auch eher selten, weil ich mir meistens zutraue, die Funktion des Codes auch Monate später sofort verstehen zu können.
Nur in längeren Methoden dokumentiere ich häufiger. So mache ich z.B. bei einer Kollisionsabfrage deutlich, welche Seite gerade geprüft wird, damit ich das später direkt finde.

Es ist sogar ein sehr gutes Zeichen, wenn du keine Doku brauchst und der Programmcode selbsterklärend ist. Manchmal wird es aber fälle geben, wo vielleicht nicht wirklich klar ist, was die Methode macht, auch wenn die Signatur klar ist. Beispielsweise wenn sich die Parameter gegenseitig beeinflussen ist es oftmals hilfreich, das zu dokumentieren.

In meinen Freizeitprojekten dokumentiere ich auch keine Methoden/Klassen, nur Workarounds oder TODOs. Meiner Meinung nach ist es, wenn man alleine arbeitet und guten Code hat, gar nicht notwendig, etwas zu dokumentieren. Bei Fehlern findet man dann schnell die fehlerhafte Methode und kann es sowieso oftmals schnell fixen. Bei wirklich vertrickten Problemen hilft dir die Doku eh nie.

In meiner Signatur sind ein paar Zitate zum Thema Softwareentwicklung und Dokumentation dabei, die sich bei mir über die Zeit angesammelt haben. Die spiegeln ein bisschen die generelle Einstellung der Branche zu dem Thema wieder... (Zum Nachlesen: http://pastebin.com/xxCXAYZG )

Falls wirklich Dokumentation erstellt werden soll ist eine beliebte Möglichkeit einen Praktikanten/Hiwi dafür einzustellen. Oder du nimmst irgendein Tool was dir die Doku automatisch generiert. Das wird meistens dann gemacht, wenn eine Dokumentation vertraglich gefordert ist, sie aber sowieso niemand ernsthaft verwendet.

Als schönes Beispiel für eine Dokumentation dieser Qualität ist auch hier: http://static.springsource.org/spring/do…actoryBean.html

Zitat

public abstract class AbstractSingletonProxyFactoryBean
Convenient proxy factory bean superclass for proxy factory beans that create only singletons.

Zitat von »dennis-.-«

Als schönes Beispiel für eine Dokumentation dieser Qualität ist auch hier: http://static.springsource.org/spring/do…actoryBean.html

Zitat

public abstract class AbstractSingletonProxyFactoryBean
Convenient proxy factory bean superclass for proxy factory beans that create only singletons.

Solche Dokumentation ist aber für die Tonne, weil sie sogar falsche Sachen behauptet.

Bei meinen privaten Projekten dokumentiere ich die öffentliche Schnittstelle eigentlich nur aus dem Grund, damit ich mir daraus auch mal ein HTML machen könnte, wenn ich es wollte.
Und damit ich ein einheitliches Bild in IntelliSense hab und nicht nur bei der Hälfte der Klassen und Methoden eine Beschreibung bekomme und bei der anderen Hälfte nicht.
Ansonsten wie hier schon mehrfach genannt wurde nur irgendwelche Besonderheiten, die sich nicht unbedingt direkt aus dem Methodennamen und/oder Parameternamen ablesen lassen.

Zum Thema Tools um Dokumentation zu erzeugen: Hin und wieder sind die auch für einen Lacher gut

Ah ja, das gute Doxygen. Solche Sachen sind üblich. Ich persönlich nutze übrigens auch Doxygen oder Javadoc, einfach damit die IDE mit die Parameter und vielleicht sogar deren Zusammenhang (z.B. welche null sein dürfen und welche nicht) aufzeigen kann.

Zitat von »TrommlBomml«

Es ist sogar ein sehr gutes Zeichen, wenn du keine Doku brauchst und der Programmcode selbsterklärend ist.

Das halt ich für absoluten quatsch. Wenn ich eine Bibliothek, die ich vor Jahren geschrieben habe, wieder raus hole und verwenden will, interessiert mich die Implementierung absolut keinen Meter. Ich werde nur im Falle eines Bugs den Code wohl jemals wieder anschauen. Ansonsten will ich eine Blackbox mit definiertem Zugriffsinterface, das so dokumentiert ist, dass ich es ohne Probleme verwenden kann. Mag sein, dass ich mit dieser Ansicht alleine da stehe. Abgesehen davon deckt sich Anspruch mit der Realität bei meinen Projekten nicht immer ganz. Zufäligerweise arbeite ich grad wieder schwer an der Dokumentation meiner öffentlichen Klassen in meiner Gameengine, nachdem sie jetzt schon einige zeit nur neue und geänderte Funktionalität erhalten hat. Überhaupt ist nicht das Dokumentieren neuer Funktionen das Problem, sondern das Nachführen existierender Dokumentation mit der Implementierung. Es gibt wohl nix schlimmeres als falsche Dokumentation. Am Ende ist es eine Frage der persönlichen Disziplin. Ich gebe zu es ist ein stetiger Kampf, aber auch befriedigend wenn man seine Doxygendoku durschaut und feststellt, dass man fast 100% dokumentiert hat. Und bei der einen oder anderen Klassen, hat die Doku mir schon geholfen mich an die interne Funktionsweise zu erinnern ohne dabei in den Code schauen zu müssen.

Für die Statistik: Ich verwende Doxygen mit graphviz im Javadoc-Stil, dazu habe ich VS-Makros die mir per Tastendruck Dokumentationsblöcke für Dateien, Klassen und Funktionen erstellen, abgeleitet aus der Signatur.