Heute hatte ich eine Diskussion über die Art und Weise wie man in Java dokumentiert. Was sind gute Kommentare? Was muss dokumentiert werden? Was kann man weglassen?
Ich finde zu diesem Thema die Meinungen von Robert C. Martin gut, die er in seinem Buch Clean Code: A Handbook of Agile Software Craftmanship. Prentice Hall PTR. 2008 unter dem Kapitel 4 “Comments” vertritt.
Ein paar Auszüge:
Seite 63:
It is just plain silly to have a rule that says that every function must have a javadoc, or every variable must have a comment. Comments like this just clutter up the code, propagate lies, and lend to general confusion and disorganisation.
Seite 64f.:
And then there’s this paragon of redundancy:
/** * Returns the day of the month. * * @return the day of the month. */ public int getDayOfMonth() { return dayOfMonth; }
Seite 71:
As useful as javadocs are for public API’s, they are anathema to code that is not intended for public consumption.
Auch wenn ich hier Auszüge aus dem Kapitel “Bad Comments” bringe, so halte ich Kommentare und Dokumentation zum Job eines Softwareentwicklers. Öffentliche Methoden müssen eine nützliche Dokumentation haben (Bitte aber nicht wie in getDayOfMonth 😉 ). Auch macht man sich oder seinen “Nachfolgern” oft das Leben wesentlich leichter seine Intention zu erklären, warum etwas genau so und nicht anders gemacht hat. Alles im Buch beschriebene möchte ich nicht hier wiedergeben. Einfach lesen.
Da aber Softwareentwicklung in den meisten Fällen im Team erfolgt, sollte man sich aber auf Regeln einigen und diese dann auch einhalten.
ollin's 
Ich programmiere zwar, weil aus Hobby, nur für mich alleine (und nicht im Team). Aber durch den Umstieg von Windows auf Mac (und damit C++ auf Java) merke ich gerade, wie sehr man auch sich selbst einen gefallen tut, wenn man den Quelltext dokumentiert, auch wenn man selbst nur der einzige ist, der das liest. 😉
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.
LikeLike
Hoi Daniel,
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.
LikeLike
Lange und intuitive Methoden- und Variablennamen verwende ich auch. Ich habe da aus den alten Windows-Zeiten gelernt, als ein Programm klein und übersichtlich war, und nach 2 Jahren konnte ich kaum mehr Fehler beseitigen oder das Programm erweitern, weil ich nahezu nichts kommentiert habe.
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.
LikeLike
Hallo Daniel,
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.
LikeLike