Software-Entwicklung: Dokumentation

[147852369]

Hallo Forum,

ich wollte Euch mal fragen, ob und wie ihr Eure Software dokumentiert.
Die, die's machen, werden wahrscheinlich nicht einfach einen Texteditor nutzen und ständig reinschreiben, wie's vorangeht. Für PHP und Java gibt es ja bereits Programme, die das automatisch machen. Nutzt ihr sowas auch?

Erzählt mal.

 

[threadi]

Ich nutze nichts dafür. Aber ich habe mir angewöhnt alles Inline zu kommentieren. Es gibt dann wiederum die Möglichkeit mit einem Script diese Kommentare auszuschneiden und als Dokument zusammenzufassen - falls man es mal braucht. In den meisten Fällen belasse ich es bei bloßer Kommentierung, da eine richtige Dokumentation viel Zeit kostet - Zeit und Geld die manche Kunden nicht haben ;)

Noch eine andere Methode ist eine Art Pflichtenheft, welches man vor der Programmierung erstellt. Dieses sollte bereits sehr nah an der Programmierung sein, d.h. es dürften schon einige Quellcode genannt werden - die Ablaufbeschreibung aber grundsätzlich in menschlicher Sprache. Das liest dann ein anderer Programmierer durch und segnet es ab bevor das beschrieben tatsächlich programmiert wird. Das hat mich bereits einige Male zu guten Konzepten für Programmierungen geführt die dann auch völlig unproblematisch fertiggestellt werden konnte.

 

[newlord]

Unser Berufsschul-Lehrer predigt uns, dass es eigentlich vollkommen Sinnfrei ist seinen Quelltext mit Kommentaren bzw. automatisch generierter Doku zuzupflastern. Seine Begründung dafür ist, dass einerseits vielleicht später die Kommentare nicht mehr mit der eigentlichen Funktionalität überein stimmen und andererseits es auch nicht nötig wird seinen Quelltext zu dokumentieren, wenn man sich zb. an die Regeln des Clean Code hält. Auch wenn der Unterricht unseres Lehrers immer sehr subjektiv abläuft: In gewisser Weise finde ich, dass da auch was dran ist. Ich habe für mich festgestellt, dass wenn man sich Mühe gibt seinen Quelltext so aufzubauen als würde man ein Buch lesen, es wirklich unnötig wird eine entsprechende Dokumentation in eben diesen reinzuschreiben. Aber auch dass ist natürlich Auslegungssache. Einen humoristischen Ansatz kann man sich vielleicht hiervon noch holen

http://sonicstealth.com/images/1261254830.jpg

 

[CPCoder]

Ich habe für mich festgestellt, dass wenn man sich Mühe gibt seinen Quelltext so aufzubauen als würde man ein Buch lesen, es wirklich unnötig wird eine entsprechende Dokumentation in eben diesen reinzuschreiben.

Und was machst du, wenn du in einer Software-Firma als Programmierer anfängst und du bekommst ein Software-Produkt, welches du weiterentwickeln sollst, dessen Quellcode aber in keinster Weise dokumentiert ist?
Eine gute Dokumentation des Quellcodes ist meiner Meinung nach Pflicht.

Gründe:
- Man kann auch nach Monaten/Jahren sich schnell wieder in den Code einarbeiten
- Andere Entwickler, die den Code weiter entwickeln wissen was die jeweiligen Methoden, Funktionen und Klassen tun, ohne den Quellcode durcharbeiten zu müssen


Nachtrag:
Ich gehe hier jetzt mal nicht von kleinen Scripten aus, sondern von ausgewachsenen Projekten, mit mehreren hundert bis tausend Zeilen Code.

 

[sysop]

Im Quelltext werden von mir die Codeteile entsprechend dokumentiert, dass ist nach meiner Auffassung ein Muss.
Und ja, ich nehme einen Texteditor und dokumentiere mit Datum was ich wo wie eingefügt und/oder verändert habe. Das ganze lege ich als History.txt den Projekten bei.
Ausserdem bin ich recht penibel, was die Versionsnummern angeht (4-Stellig), da ich den Stand mit der History abgleichen kann und einen Überblick über Updates etc bekomme.

 

[newlord]

Und was machst du, wenn du in einer Software-Firma als Programmierer anfängst und du bekommst ein Software-Produkt, welches du weiterentwickeln sollst, dessen Quellcode aber in keinster Weise dokumentiert ist?

Wenn es sich dabei um guten Code handelt, ist das - wie ich bereits erwähnte - für MICH weniger problematisch. Bei schlechtem Code dauert's halt länger den Durchblick zu bekommen, aber in beiden Fällen würde ich dann für solche Arbeiten auch von jener Firma bezahlt. Wie sagte es Bodo Wartke mal: "Da muss er durch"

Ich gehe hier jetzt mal nicht von kleinen Scripten aus, sondern von ausgewachsenen Projekten, mit mehreren hundert bis tausend Zeilen Code.

Das hab ich auch nicht erwartet. Das größte was ich mal hatte waren geschätzte 20k Zeilen mit sehr mangelhafter Doku. Ich sage nicht dass es leicht war aber es war auch nicht unmöglich.

 

[ka9de]

Wenn es sich dabei um guten Code handelt, ist das - wie ich bereits erwähnte - für MICH weniger problematisch.

Ich denke es geht weniger darum an eine Schleife zu schreiben "hier beginnt eine Schleife, die alle Daten ausliest".
Es geht darum am Anfang zB einer Methode zu schreiben was diese macht, was Input/Output ist und zB von wem sie geschrieben ist. Ich möchte nicht eine fremde Funktion mit 40 Zeilen bekommen und mir diese durchlesen um zu erkennen dass da ein Datenbankeintrag gemacht wird.

Zum Thema: Ich entwickel keine Software, daher kommentiere ich nicht. Für ein paar PHP Scripte für mich selbst schreib ich zu den Funktionen dazu, was sie machen..

 

[CPCoder]

Ich denke es geht weniger darum an eine Schleife zu schreiben "hier beginnt eine Schleife, die alle Daten ausliest".
Es geht darum am Anfang zB einer Methode zu schreiben was diese macht, was Input/Output ist und zB von wem sie geschrieben ist. Ich möchte nicht eine fremde Funktion mit 40 Zeilen bekommen und mir diese durchlesen um zu erkennen dass da ein Datenbankeintrag gemacht wird.

Genau darauf wollte ich auch hinaus mit meinem Beitrag, Danke )

 

[Asterixus]

Unser Berufsschul-Lehrer predigt uns, dass es eigentlich vollkommen Sinnfrei ist seinen Quelltext mit Kommentaren bzw. automatisch generierter Doku zuzupflastern. Seine Begründung dafür ist, dass einerseits vielleicht später die Kommentare nicht mehr mit der eigentlichen Funktionalität überein stimmen und andererseits es auch nicht nötig wird seinen Quelltext zu dokumentieren, wenn man sich zb. an die Regeln des Clean Code hält. Auch wenn der Unterricht unseres Lehrers immer sehr subjektiv abläuft: In gewisser Weise finde ich, dass da auch was dran ist. Ich habe für mich festgestellt, dass wenn man sich Mühe gibt seinen Quelltext so aufzubauen als würde man ein Buch lesen, es wirklich unnötig wird eine entsprechende Dokumentation in eben diesen reinzuschreiben. Aber auch dass ist natürlich Auslegungssache. Einen humoristischen Ansatz kann man sich vielleicht hiervon noch holen

http://sonicstealth.com/images/1261254830.jpg

Das ist aber vollkommener Quatsch. Diese Kommentar-Dokumentation ist meiner Meinung nach sehr wichtig (außer in Java, wo alles explizit im Code selbst erwähnt werden muss). Alleine für die Code-Completion ist es wichtig zu wissen, was eine Methode verlangt oder zurückgibt.

 

[CPCoder]

Das ist aber vollkommener Quatsch. Diese Kommentar-Dokumentation ist meiner Meinung nach sehr wichtig (außer in Java, wo alles explizit im Code selbst erwähnt werden muss).

Es ist egal in welcher Sprache man programmiert, aber eine gute und ausreichende Dokumentation gehört immer dazu. Die Sprache Java bildet hier auch keine Ausnahme!