JAVA Code in Dokumentation erklären

[pl4gu33]

hey,... ich schreibe gerade an einer Dokumentation und muss in dieser meinen Code erklären....

dabei gehe ich im Moment wie folgt vor,... ich beschreibe ein Szenario anhand von Abläufen d.h. ich sage was passiert, wenn z.b. eine bestimmte Aktion ausgeführt wird. Bloß irgendwann komme ich zu einem Punkt, wo ich dann zum Beispiel sowas habe....

Pseudocode mäßig dargestellt:

Methode1 (...){

variablen zuweisung = Methode2(...)
for Schleife{
   Methode3(...)
}

so nun will ich dieses Szenario beschreiben, aber Methode 2 und 3 beinhalten auch etwas mehr Code/ andere Methoden. Daher versuche ich die auch irgendwie nebenbei zu erklären und irgendwie endet das im Chaos

Ich könnte jedem mündlich klar machen, was genau in dem code passiert und das würde auch jeder locker verstehen bloß schriftlich sieht das für mich etwas komisch aus, wenn man nicht die ganze Klasse direkt sieht und nur Methode für Methode abhandelt

Daher wollte ich mal fragen, wie ihr solche Methoden abfolgenden erklären würdet, dass sie ein Aussenstehender ohne den ganzen Code zu sehen versteht,... weil irgendwie will ich dann Zeile für Zeile erklären bloß finde ich irgendwie ist das nicht sinn und zweck ...

eine weitere Frage dazu wäre, sollte man die Kommentare drin lassen in einer Doku ?

 

[maki]

Man dokumentiert imho nur public und protected Methoden/Variablen.

Dabei beschreibt nur was passiert, aber nicht wie, letzteres ist ein Implementierungsdetail und ist meistens durch die Implementierung selber am besten beschrieben.

 

[nillehammer]

Mag sich wie eine Plattitüde anhören, aber ich finde, der Code muss die Doku sein. Das ist natürlich nicht bis in letzter Konsequenz durchzuhalten, aber das ist für mich die Richtschnur. Kommentare werden mit zunehmender Weiterentwicklung des Codes alt und am Ende lügen sie sogar, weil sie etwas anderes dokumentieren als der weiterentwickelte Code macht. Dazu vielleicht ein kleines Beispiel:
Schlecht:

// Prfüfen, ob Alter größer 18, also erwachsen
if (age > 18) {
  machwas();
}

Gut:

if (isAdult(age)) {
  machwas();
}

private boolean isAdult(int age) {
  return age > 18;
}

Ansonsten bin ich bei Maki. Methoden, die aufgrund ihrer Sichbarkeit Teil des APIs Deines Codes werden, sollten so dokumentiert sein, dass ein anderer Entwickler sie leichter benutzen kann. Dazu am besten Javadoc-Kommentare (/**) benutzen.