Richtige Dokumentation eines Java Programms

[Letavino]

Hallo, ich hoffe, dies ist der richtige Bereich hierfür!
Ich bin gerade dabei eine Technische Dokumentation eines Java Programms von mir zu schreiben, welche einen Einblick für andere bieten soll, die mit dem Programm arbeiten, aber auch für diejenigen, die im Quellcode des Programms Änderungen vornehmen möchten.

Bisher habe ich:
- Eine Einleitung mit Vorbemerkungen
- Eine Erklärung der verwendeten Datenbanken
- Die Aufgabenstellung, Anforderungen und Ziele des Programms
- Eine Beschreibung der Benutzeroberflächen
- Eine grobe Struktur der Dateien und deren Beschreibung
- Datenbankendiagramme
- Einen Abschnitt zum Programmtest
- Und schließlich eine Zusammenfassung

- Der Quelltext ist kommentiert und mit JavaDoc ausgestattet

Doch fehlt eine genauere Übersicht über den Programmablauf. Bei meinem letzten PHP Projekt konnte ich dazu für die wichtigsten Dateien PAP's erstellen, bei meinem Java Code scheint das so nicht möglich zu sein, da der Programmablauf nicht so linear ist.
Welche Form der Darstellung würde sich hier anbieten?
Gibt es Programme, die soetwas automatisch aus dem Code heraus erstellen können?
Programme für UML habe ich bereits gefunden, fand die darstellung aber irgendwie sehr nichts-sagend.

Mfg, Florian

 

[Guardi]

UML ist aber der Standard 😉

Klassendiagramme (Architektur) und Sequenzdiagramme (Ablauf) sind sogar must-haves!
Du wirst dich damit wohl ein bisschen beschäftigen müssen.
Allerdings ist es immer einfacher Diagramme aus fertigem Code zu stricken als konzeptionell welche zu erstellen für wein Projekt, dass man zukünfitg umsetzen möchte.

 

[Wildcard]

Allerdings ist es immer einfacher Diagramme aus fertigem Code zu stricken als konzeptionell welche zu erstellen für wein Projekt, dass man zukünfitg umsetzen möchte.

Das ist dann auch genau die Art von UML Diagramm mit der niemand etwas anfangen kann 😉

 

[schalentier]

Ich weiss ja net, was fuer ein Programm du geschrieben hast, aber normalerweise macht man zwei Dokus. Eine fuer den Anwender und eine fuer Entwickler. Das Ziel sollte es sein, das beide Dokus so lang wie noetig, aber so kurz wie moeglich sind. Erreichen kann man das ueber eine intuitive Oberflaeche mit sinnvollen Tooltips fuer den Anwender und einfachem, logischem Quellcode mit durchdachten Klassen-/Methodennamen fuer den Entwickler.

Fuer Anwender:

- Die Aufgabenstellung, Anforderungen und Ziele des Programms

Sehr wichtig, hier sollte viel Gehirnschmalz drin stecken

- Eine Beschreibung der Benutzeroberflächen

Haengt von der Komplexitaet der Anwendung ab, sollte soweit moeglich selbstklaerend sein. Hauptproblem hier ist, wie haelt man die Beschreibung mit der Anwendung selbst aktuell?

Fuer Entwickler:

- Eine Erklärung der verwendeten Datenbanken

Okay

- Eine grobe Struktur der Dateien und deren Beschreibung

Sehr praktisch, wenn man mit Maven arbeitet aber vergleichsweise unwichtig, da das Projektlayout immer gleich ist

- Datenbankendiagramme

ER Diagramme? Wird das generiert? Ansonsten wuerd ich nur die wichtigsten Tabellen, Beziehungen und Felder beschreiben.

- Einen Abschnitt zum Programmtest

Schoen, hier sollte erklaert werden, wie man schnell einen Unittest schreibt, vielleicht irgendwas ueber bestehende Mock-Strukturen, etc.

- Der Quelltext ist kommentiert und mit JavaDoc ausgestattet

Kann nicht schaden ;-)

Welche Form der Darstellung würde sich hier anbieten?

Sequenzdiagramme

Gibt es Programme, die soetwas automatisch aus dem Code heraus erstellen können?
Programme für UML habe ich bereits gefunden, fand die darstellung aber irgendwie sehr nichts-sagend.

Ja gibt es, ist im meinen Augen aber Humbug. Ich wuerd maximal den Ablauf einiger weniger kritischer Stellen per UML dokumentieren. Hier gilt wie fuer die gesamte Doku, weniger ist oft mehr.

Das Problem an ausfuehrlicher Dokumentation ist die Aktualitaet. Niemand hat Lust, das gerade Programmierte noch an zig Stellen in riesigen Word-Dokumenten nachzupflegen. Fuer mich haben sich UserStories als hervoragendes Mittel herausgestellt. Da beschreibt man "nur", wer was in der Anwendung machen kann. Aber nicht das wie, denn das steht im Code.

Aber wie immer, es haengt sehr stark von der Anwendung ab.

 

[Andi_CH]

Das ist dann auch genau die Art von UML Diagramm mit der niemand etwas anfangen kann 😉

Ich muss dir bepflichten. Ich habe noch nie brauchbare UML Diagramme gesehen, die aus Code generiert wurden und nicht massiv überarbeitet wurden.

UML Diagramme werden zuerst erstellt und dann wird anhand dieser der Code erstellt bzw. zum Teil automatisch generiert.
Am Schluss (nobody is perfect) braucht es sicher noch etwas Feintunig an den Diagrammen weil der Code ja "organisch" gewachsen ist.

Das Eingangsposting so als Inhaltsverzeichnis betrachtet sieht nicht recht gut aus.

 

[Letavino]

Ok, vielen Dank für die guten Antworten!
Ich denke, da muss ich noch ein bisschen nacharbeiten und ich werde das nächste Projekt auch erstmal mit einer ausgedehnteren Planungsphase beginnen.

Ihr habt mir wirklich wietergeholfen. 🙂

mfg, Florian