Software Dokumentieren für Eigenbedarf, nur wie?
-
Hallo Ihr Lieben, ich weiß jetzt nicht ob hier richig bin, aberich versuchs halt mal.
Wenn man Programme schreibt, wirds ja irgendwann immer unübersichtlicher. Irgendwann hat man nen haufen Klassen, Funktionen, Variablen uvm.
Guckt man sich nach nem halben Jahr einen bestimmten Teil des Quellcodes wieder an um zB. einen Fehler zu finden, blickt man nicht mehr durch und weiß nimmer wie und warum man das so und so gemacht hat. Man muss sich erst wieder einlernen.
Kommentare im Quellcode helfen ein wenig, aber man kann ja nicht Seitenweise Kommentare schreiben.
Nun die Frage:
Wie Dokumentiert Ihr/man seine Programme?Aus der Schule kenn ich noch so Sachen wie Struktogramm, PAP und was weiß ich.
Von Java her kenne ich UML.Was gibts da für C/C++?
Wie macht Ihr das?
Aufmalen und rein in den Ordner oder gibts da Programme dafür usw.Würde mich mal interessieren bzw. wäre es mir eine Hilfe zu Wissen wie man sowas macht.
Im einfachsten Fall einfach aufschreiben:-)Grüße Mondmann
-
Weil ich zum Aufmalen einfach nicht komme und es morgen sowieso wieder veraltet ist, nutze ich haufenweise Kommentare.
Und ich versuche immer möglichst sprechende Namen zu haben. Das spart die Doku teilweise wieder.
Und wenn man sich in etwa immer an ein Schema hält, ist der Wiedererkennungswert auch höher und man findet sich leichter zurecht.
-
Mondmann schrieb:
Kommentare im Quellcode helfen ein wenig, aber man kann ja nicht Seitenweise Kommentare schreiben.
Doch kann man. Der Rekord in einer unserer Dateien ist bei ca. 8 DinA4 Seiten reiner Doku Text am Anfang der Sourcedatei.
Allerdings tendieren wir eher dazu bei größeren Projekten Verweise auf externe Projektdokus mit anzugeben.Aber wie gesagt. Funktionsköpfe mit 60-100 Zeilen Beschreibung sind bei uns keine Seltenheit.
Dazu erfolgt ein Change-Log für jede Änderung, das Kompakt gehalten wird auf 2 Zeilen pro Änderung oder Bugkorrektur.
Nach meiner Ansicht gehört soviel wie möglich in den Sourcecode. Gerade die Dinge die Trickreich sind und beim fixen der ersten Bugs Problemstellen beheben gehören am ausgiebigsten dokumentiert. Gerade in dieser Projektphase wenn alles nur noch auf die Auslieferung hinläuft wird am aller schludrigsten dokumentiert.
Just my 2 cents
-
Hm...ich hab schon länger angefangen meine Änderungen in ne Excel Tabelle zu klopfen...geht irgendwie schon ist aber nicht das gelbe vom Ei.
Wird das Programm nicht größer mit Seitenweise Kommentare oder tut das nichts zur Sache?
-
Mondmann schrieb:
Hm...ich hab schon länger angefangen meine Änderungen in ne Excel Tabelle zu klopfen...geht irgendwie schon ist aber nicht das gelbe vom Ei.
Wird das Programm nicht größer mit Seitenweise Kommentare oder tut das nichts zur Sache?Wieso soll das Programm größer werden. Die Kommentare ignoriert der Compiler dich alle...
-
Mondmann schrieb:
Hm...ich hab schon länger angefangen meine Änderungen in ne Excel Tabelle zu klopfen...geht irgendwie schon ist aber nicht das gelbe vom Ei.
hi,
benutz für sowas besser ein versionskontrollsystem wie z.b. subversion: http://subversion.tigris.org/
damit kannste z.b. beim einchecken kommentare hinzufügen was sich geändert hat usw. du kannst auch quelltexte mit der vorgängerversion vergleichen und siehst änderungen und vieles mehr...
das kann man auch wunderbar lokal einsetzen, also nicht nur serverbasiert...
-
Dokumentieren: doxygen. Kann auch schöne Diagramme erstellen, gleich Haufenweise wenn man alles aufdreht. Also die üblichen wer mit wem und von wem (Vererbung etc.), aber auch wer ruft was auf/wird von wem aufgerufen - diese netten Dinge eben.
Plus natürlich kann er aus entsprechend formatierten Kommentaren ne HTML/TEX/CHM/... Hilfe machen.
-
Also als Versionssystem nutze ich seit längerem Tortoise CVS.
Gefällt mir sehr gut.
Doxygen ist spitzenmäßig!
Mann mus im Quelltext seine Sachen Dokumentieren und hat sie nachher auch extern verfügbar, wenn man mal nur "schnell" was gucken will. Super!
Vielen Dank für den Tip, Mondmann
-
Der beste Weg, Zweck, Architektur, Implementierung von Software zu dokumentieren, sind mit Sicherheit sog. Specification Cards.
Mehr dazu hier: [url]http://greiterweb.de/spw/wie_docugestalten.htm
Man kann die Summe all solcher Karten dann (automatisch) nach HTML bringen.
Was so entsteht, nenn ich ein Project Web.Hier ein Beispiel: [/url]http://greiterweb.de/spw/xs_wissDB/1/1.htm
und hier das Werkzeug, mit dem ich diese HTML-Präsentation meines Software-Entwurfs erzeugt habe:
[url]http://greiterweb.de/spw/meinprojweb.htm
-
Wer den - überaus empfehlenswerten - Weg geht, Software mit Hilfe sog. Specification Cards zu entwerfen und wartungsfreundlich zu dokumentieren, der sollte dazu vorgehen, wie beschrieben in [url]<a href=http://greiterweb.de/spw/TopDown.htm>Top Down Design per Specification Card</a>.[/url]
