# Richtige Dokumentation eines Java Programms



## Letavino (26. Mai 2011)

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 (26. Mai 2011)

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 (26. Mai 2011)

> 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 (27. Mai 2011)

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:


Letavino hat gesagt.:


> - Die Aufgabenstellung, Anforderungen und Ziele des Programms


Sehr wichtig, hier sollte viel Gehirnschmalz drin stecken


Letavino hat gesagt.:


> - 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:


Letavino hat gesagt.:


> - Eine Erklärung der verwendeten Datenbanken


Okay


Letavino hat gesagt.:


> - Eine grobe Struktur der Dateien und deren Beschreibung


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


Letavino hat gesagt.:


> - Datenbankendiagramme


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


Letavino hat gesagt.:


> - Einen Abschnitt zum Programmtest


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


Letavino hat gesagt.:


> - Der Quelltext ist kommentiert und mit JavaDoc ausgestattet


Kann nicht schaden ;-)



Letavino hat gesagt.:


> Welche Form der Darstellung würde sich hier anbieten?


Sequenzdiagramme



Letavino hat gesagt.:


> 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 (27. Mai 2011)

Wildcard hat gesagt.:


> 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 (27. Mai 2011)

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


----------

