Wenn man allein programmiert wie Du, ist der Grad an Dokumentation am besten, der einen am besten arbeiten lässt. Ich bin der festen Meinung das Spass eine wichtige Rolle dabei spielt. Den sollte man nicht verlieren.

Im Moment schreibe ich viel vom Code um, weil ich immer mehr dazulerne und quasi Dinge, die vorher der GUI-Builder erstellt hat (z.B. die ganzen Listener) jetzt aus dem GUI-Builder entferne und manuell neu schreibe – da hat man schnelleren Zugriff und weitere Vorteile…

Zur Zettelkasten-Doku: Für Version 3 wird die gesamte Doku in die Wiki verlegt und etwas neu strukturiert (bzw. ist schon geschehen, nur Inhalte fehlen). Mitunter ist weniger mehr, weil man sonst vor lauter Informationen gar nicht weiß, wo man was findet.

Und nein, OpenSource gibt es da noch nicht zu finden. Aber vielleicht kommt das noch irgendwann.

war die letzten Tage nicht vor dem Computer und deshalb erst heute.

public und protected Methoden zu dokumentieren halte ich auch für zwingend notwendig. Dazu gehört natürlich auch, was die Methode genau macht und welche Vorbedingungen eingehalten werden müssen und welche Nachbedingungen von der Methode erfüllt werden.

Bei package oder private Methoden gehe ich danach vor, wie wichtig und stabil die Methoden sind. Sind sie zentral, d.h. für das Gesamtverständnis wichtig, dann ist eine Dokumentation auch hier notwendig. Ansonsten investiere ich lieber die Zeit mir einen guten Methodennamen auszudenken.

Zwischen den Zeilen dokumentiere ich wirklich wenig. Ich mache es dann, wenn ich wirklich etwas komisches machen muss und ich dem Nachfolger (ja, auch mir ) klar machen möchte, warum so und nicht anders.

Wenn die Methoden- und Variablennamen gut gewählt sind, dann liesst sich der Code unter Umständen schon von selbst.

Kunde einKunde = ...
Einkaufswagen einkaufswagen = ...
einKunde.nimmtEinkaufswagen(einkaufswagen);
Artikel artikel = ...
einkaufswagen.legeHinein(artikel);
...
Kasse kasse = ...
kasse.scanneAlleArtikelIm(einkaufswagen);
kasse.druckeQuittung()


Ist doch besser als:

A a = ...
B b = ...
a.setB(b);
C c = ...
b.add(c)
...
K k =
k.doIt(b)
k.print()

Beim ersten Beispiel finde ich, ist der Code selbst-sprechend. Das Zweite müsste dokumentiert werden, da es zu unverständlich ist. Ich ziehe es in einem solchen Fall vor, lieber die Methoden umzubenennen anstatt den Code mit Kommantar grösser zu machen. Wenn eine Umbenennung nicht möglich ist, z.B. weil einem der Code nicht gehört, dann muss man natürlich mit Kommentaren arbeiten. Ist aber in meinen Augen eine Notlösung.

Deine umfangreiche Dokumentation für den Zettelkasten auf den Webseiten ( http://zettelkasten.danielluedecke.de/ ) finde ich übrigens sehr gut. Leider konnte ich mir den Source nicht anschauen

Gruss Oliver
PS.: Schau dir mal “Clean Code” an. Ist sehr Java-orientiert und deshalb für Dich sicher gut zu lesen.

Was ich persönlich gerne mache: Eine ausführliche Beschreibung, was die Methode macht, in die JavaDoc setzen, und wenn es ähnliche Methoden gibt, auf diese dann per @link verweisen. Sehr wichtig finde ich dies für Klassen, die irgendwie mit Datenverwaltung zu tun haben, also das elementare Innenleben eines Programms darstellen. Oft weiß ich nämlich selbst nicht mehr genau: macht Method A nun das, was ich wollte, oder eher B?

Darüberhinaus kommentiere ich aber auch ganz viel in der Methode selbst. Nahezu jede Code-Zeile hat mindestens eine Kommentarzeile. Das liegt aber an meinem Programmierstil: Ich habe eine Idee, fang an, die Methode zu schreiben, ohne Kommentare, nur Code. Und wenn ich fertig bin, dann kommentiere ich meine einzelnen Schritte in der Methode, damit ich noch weiß, was ich gerade gemacht habe. Anschließend, oder später, schreibe ich das JavaDoc. Wenn ich das erst später mache, sind die Kommentare in der Methode recht hilfreich, um nachzuvollziehen, was ich gemacht habe.

Ich habe mir eigentlich angewöhnt, nahezu jede Zeile zu kommentieren, weil ich keine “zusammenklebenden” Code-Zeilen mag. Ist also mitunter auch aus optischen/ästhetischen Gründen, aber meistens macht der Kommentar auch Sinn.