spieleprogrammierer.de - Forum und Wiki zur Spieleprogrammierung und Spieleentwicklung

Zitat von »Thoran«

Mag sein, dass ich mit dieser Ansicht alleine da stehe.

Stehst du nicht. Ich kenne es zu gut, wenn man Code hervor holt, den man vor 6+ Monaten geschrieben hat und keinen blassen Schimmer mehr hat, was da wie funktioniert hat und nur die Klassen und public Methoden sieht und auch nur diese Schnittstelle sehen will. Erst wieder den Code lesen zu müssen, um zu wissen, wie man es benutzt, ist keine Option.

Zitat von »LetsGo«

Naja kommt wohl drauf an in welchem Umfeld man ist.
Bei einem privaten Projekt ist es natürlich eher weniger von Interesse, dass etwas dokumentiert ist.

Ich hab wohl vergessen, deutlich zu machen, dass ich gerade im privaten Umfeld Wert auf Dokumentation lege.

Doch, doch, du hast das schon ganz deutlich gemacht und ich auch. LetsGo hat das aber einfach ignoriert.

Ich glaube ich habe ein recht eigenwilliges vorgehen was Dokumentation angeht, zumindest im privaten Umfeld was ich so bisher gesehen habe.

Konvention vor Dokumentation.

Ich arbeite sehr konventionsgesteuert. Vor jeder eigentlichen Dokumentation/Code habe ich ein Dokument in dem ich recht genau beschreibe wie der Code/API und die Dokumentation auszusehen hat (Dafür habe ich eine Vorlage die ich dann nur noch für das aktuelle Projekt anpasse, wenn es überhaupt nottut).
Ich versuche möglichst über Projektgrenzen hinweg den Style immer bei zu behalten. Insbesondere meiner APIs. Insbesondere Trenne ich ganz klar zwischen API und Code Dokumentation. Bei der Code Dokumentation versuche ich mich ein wenig an weniger ist mehr zu halten und bei der API an Vollständigkeit.

Ziel ist es möglichst alles (Über Projekte hinweg) einheitlich zu gestalten. Etwas was ich als deutlich angenehmer empfinde wenn ich alte Projekte auskrame. Einen sprachlich geschickten Ausdruck versuche ich sogar tunlichst zu vermeiden. Insbesondere was die API Dokumentation angeht, hier soll eigentlich alles gleich aussehen. Die Benutzung sollte keinen so hohen Wissensstand benötigen. Die Code Dokumentation sollte primär der Code selbst sein, ansonsten so prägnant wie möglich.

Technisch benutze ich auch gerne die XML Dokumentation speziell für die API. Da sie sich wenn man sie richtig einsetzt gut in die meisten IDEs integriert. Und da man sie recht einfach vom Code trennen kann und eine eigene API Doku erstellen kann.

Aber wie gesagt das ist so meine Art wie ich gut klar komme und nichts für jemanden der einfach nur mal so drauf los coden will. Wichtig finde ich aber auch zu wissen wann man von seinen eigenen Regeln abweicht muss um sich selbst kein Bein zu stellen

Für meine APIs schreibe ich Doc-Comments im Doxygen-Format. Ich finde, dieses Format gehört noch zu den kleineren Übeln, weil es von vielen IDEs unterstützt wird und optisch nicht so negativ ins Auge fällt. Allgemein gefallen mir besonders die Doc-Comment-Formate, die nicht als solche auffallen. Natural Docs wäre hier ein gutes Beispiel. XML-Dokumentationen gefallen mir nicht so gut, weil dort das Format für meinen Geschmack zu sehr im Vordergrund steht.

Normalerweise dokumentiere ich konsequent einfach alles, was zur API gehört; auch Methoden, deren Zweck (für mich) offensichtlich ist. Dadurch ist alles einheitlich und explizit dokumentiert. Parameter und Rückgabewerte dokumentiere ich allerdings nur dann separat, wenn sie nicht aus dem Beschreibungstext hervorgehen.