Software-Dokumentation

[Gentleman]

Hallo Delphi-Gemeinde!

Ich habe im Zuge meines Studiums die Aufgabe bekommen, eine Software zu entwicklen. Dazu soll ich eine Dokumentation schreiben, am besten so, dass auch später andere Entwickler etwas damit anfangen können.
Nun habe ich schon etwas im Internet recherchiert aber leider keine konkreten Informationen finden können. Ich suche eigentlich soetwas wie eine kleine Anleitung zum Thema Software-Dokumentation. Da sich hier ja nun schon einige erfahrene Entwickler finden, wollte ich nun einfach mal direkt fragen.

Wie schreibt ihr solche Dokumentationen, einfach so "frei Hand" oder gibt es dazu vielleicht irgendwelche Vorlagen, an denen man sich orientieren könnte? Und was soll eigntlich in so einer Dokumentation stehen, was ich wichtig für Entwickler, was ist wichtig für die Anwender?

Ich bin für alle Tipps dankbar, die mir da weiterhelfen könnten!

Vielen Dank!

Gruß

[Hansa]

Stelle dir mal zuerst die frage, was du selber von einer "dokumentation" erwartest. Beispiele gibt es in jedem handbuch.

[rweinzierl]

Hallo

Wenn es darum geht das sich andere Entwickler zurechtfinden dann empfehle ich die Dokumentation im Quellcode !

Mit Programmen wie pasdoc ... kannn aus diesen Kommentaren eine Dokumentation erstellt werden.

mfg


Reinhold




--------------
www.ithof.de Arzneimitteldokumentation

[Phoenix]

Zitat von Gentleman:

Ich habe im Zuge meines Studiums die Aufgabe bekommen, eine Software zu entwicklen. Dazu soll ich eine Dokumentation schreiben, am besten so, dass auch später andere Entwickler etwas damit anfangen können.

Quellcode-Dokumentation wurde schon angesprochen.
Beachte dabei aber bitte folgendes: Versuche, keine Redundanten Informationen zu dokumentieren.
In einem 5-Zeilen Dokumentationsheader vor einer Funktion erst nochmal den Namen, den Rückgabetyp und die Parameter samt ihrem Namen aufzuführen und mit maximal 2 bis drei 3 worten zu ergänzen ist keine Dokumentation. Der Nachteil liegt auf der Hand: Änderst Du die Methode und vergisst diese 'Doku' anzupassen (Du glaubst gar nicht, wie schnell man sich sagt 'Das mach ich nachher' und macht es dann doch nicht), dann ist die Doku nicht nur ein wenig veraltet, sondern sogar falsch. Wer sich dann daran hält hat ein Problem und muss erst nachforschen.

Also wenn Doku im Quellcode, dann nur wichtige Dinge wie 'Warum' wurde das hier so gelöst.

Der beste Quellcode spricht für sich. Also anstelle von idxCtr bitteschön den Namen IndexCounter verwenden, eine Funktion nicht Person.DelAll sondern Person.DeleteRecordWithAllDependencies nennen.
Du glaubst gar nicht, wie etwas längere, treffendere Namen den Quellcode vereinfachen.

ABER: Ein anderer Entwickler lernt am besten aus Beispielen.

Wenn Du diese Software von null an entwickelst, dann gewöhne Dir gleich hierbei an, Unittests zu schreiben. (Test Driven Development ist das Stichwort).

Das hat mehrere Vorteile:
Andere Entwickler können die Tests als Beispiel nehmen. Denn hier wird die Klasse verwendet um etwas zu tun. Und wie das getan wird ist im Test schön einfach gezeigt. Eine bessere Doku für Entwickler gibt es nicht, insbesondere nicht, wenn der Test sauber benannt ist: TestDeletePerson oder TestRenamePerson. Der zweite Vorteil: Änderst Du etwas so, dass es einen Seiteneffekt hat, dann wird Dir ein fehlschlagender Test zeigen, dass so etwas passiert ist. Änderst Du etwas so, dass sich eine Methode ändert, kompiliert das 'Beispiel' nicht mehr. Das heisst, Du hast entweder etwas nicht weit genug bedacht, oder der alte Test ist durch neue Anforderungen weggefallen oder musste sich auch ändern.

Ich empfehle Dir vielleicht vorher einen Blick in das Buch 'Clean Code' von Robert C. Martin zu werfen , da steht vieles dazu drin, wenn auch nicht auf die Dokumentation bezogen sondern allgemein über sauberen und wartbaren Quellcode. Imho sollte sich niemand Informatiker Schimpfen dürfen, der das nicht gelesen hat

[Gentleman]

Zitat:

Wenn es darum geht das sich andere Entwickler zurechtfinden dann empfehle ich die Dokumentation im Quellcode !

Ntürlich könnte ich im Quellcode dokumentieren, klingt auch durchaus sehr sinnvoll, allerdings wollte ich die Dokumentation schon gerne gesondert verfassen, d.h. in soetwas wie einem "Handbuch".
Der Grund ist, dass ich zwar auch möglicherweise mal ein anderer Entwickler in dem Code zurecht finden soll, aber es geht mir auch zu einem großen Teil darum, meine Arbeit zu dokuemtieren, da ich das Programm dann auch abgeben werde.

Zitat:

Stelle dir mal zuerst die frage, was du selber von einer "dokumentation" erwartest. Beispiele gibt es in jedem handbuch.

Die Frage habe ich mir natürlich auch schon gestellt, allerdings ist es natürlich immer schwierig sich zu überlgen, was man erwartet, wenn man noch gar keine Erfahrungen in diesem Themengebiet hat.
Was wäre denn z.B. ein Handbuch, in dem ich dazu nährere Informationen finden könnte?

Zitat:

ABER: Ein anderer Entwickler lernt am besten aus Beispielen.

Das klingt logisch. Beispiele könnten natürlich auch in meiner Dokumentation eine wichtige Rolle Spielen. Ebenso wie der suaber strukturierte Quelltext, das scheint mir natürlich die Grundlage des Ganzen zu sein.

Gibt es denn z.B. so etwas wie Gundregeln, z.B. was dokumentiere ich eigentlich, was nicht? Oder was muss ich genauer erläutern und was ist selbsterklärend?

Gruß