Softwareentwicklung im Team – Teil 4 – Dokumentation

In den letzten beiden Artikeln ging es darum, dass der Build für sämtliche Entwickler gleichermaßen einfach durchzuführen ist. Wenn das Projekt sich erst einmal kompilieren und deployen lässt, steht jeder Entwickler vor einem ganz anderem Problem: was macht der Source eigentlich?

3. Problem / Beispiel
Fehlende Dokumentation
Gerade wenn Entwickler im Urlaub sind, macht es sich immer wieder bemerkbar, dass Source eben doch nicht immer selbsterklärend ist! Außerdem ist ein ständiges (Fremd-)Source-lesen kontraproduktiv, welches meist nötig wird, wenn die Parameternamen nicht selbsterklärend sind.

Lösungsvorschlag
– Jede Klasse sollte zumindest einen einleitenden Kommentar enthalten, mit einer kurzen Beschreibung, wofür diese Klasse ist.
– Jede öffentliche Methode sollte zumindest einen kurzen Kommentar über die Funktionalität enthalten, sowie sämtliche Parameter sollten mit der @param-Annotation beschrieben werden. Ebenso der Rückgabewert und Exceptions die bewußt geworfen werden. Man könnte sich darauf einigen, dass Standard-Methoden davon ausgenommen werden könnten. Z.B.:

protected ModelAndView handleRequestInternal(HttpServletRequest request, HttpServletResponse response) throws Exception {

Hier könnte es ausreichend sein, neben einen Kommentar den Rückgabewert zu beschreiben.

– Auch wenn es nervig ist, sollten Setter und Getter zumindest dokumentiert werden! Manchmal kann man sich nämlich nicht aus dem Namen herleiten, wofür ein Getter / Setter verwendet werden sollte.
Beispiel: Die Methoden setLink / getLink in der Klasse NaviEntry, welche einen Menü-Eintrag darstellt, könnte eigentlich so verstanden werden, dass dort auf den Link zugegriffen werden kann, welcher hinter dem Menü-Eintrag hinterlegt ist. Nur leider werden dort Zahlen als String injiziert. Was machen diese Zahlen? Was sagen sie aus? Wo werden sie wie interpretiert? Ich glaube, das Problem ist klar geworden.

Vorteile
– Man muss sich nicht ständig in fremden Source einlesen

Nachteile / Probleme
– Es muss gemacht werden! (könnte man automatisch prüfen lassen, dazu später mehr)
– Dokumentation kann veralten. Das kann leider nicht automatisch geprüft werden.

Aufwand
– Wenn man das mal vergleicht, mit dem ständigen Nachfragen, Debuggen, etc., relativ gering.

Rückblickend gesehen…

Zugegeben ich bin bei diesem Thema, soweit es andere betrifft, ein wenig pedantisch. Merke gleichzeitig aber, dass man viel zu häufig der Versuchung erliegt, erst einmal die Funktionalität fertig zu stellen, um die Dokumentation nachträglich einzufügen. Wie häufig man das später tatsächlich macht, kann wohl jeder beantworten, der über ein Hello-World-Programm hinaus ist.
Dokumentation ist ein leidiges Thema. Zum einen sollte Dokumentation nicht dem Selbstzweck dienen, also nicht nur geschrieben werden, damit man behaupten kann, dass man dokumentiert hätte. Ein “füllen” von Seiten ist nicht das primäre Ziel der Dokumentation (schöne Geschichte, dass das nicht überall so gesehen wird, gibt es hier http://thedailywtf.com/Articles/Very,_Very_Well_Documented.aspx). Zum anderen sollte man nicht voraussetzen, dass andere Entwickler die gleiche Denkweise haben und alles intuitiv im Source finden. Als ich einmal kurzzeitig in einem fremden Projektteam aushelfen sollte und ich nach ggf. vorhandener Dokumentation fragte, tippte sich einer der Entwickler an den Kopf und sagte: “Alles hier drin.” Und nein, das war kein Scherz. Es gab keine Dokumentation! Weder in den Sourcen, noch sonst wo. Herzlichen Dank.
Wichtig ist es also, ein gesundes Mittelmaß zu finden, wo meiner Meinung nach Quantität wesentlich höher als Qualität bewertet werden sollte. Während Software respektive Sourcecode langsam auf der Festplatte rottet, ist dieser Prozess bei Dokumentation leider um ein vielfaches schneller. Wie häufig liest man Anleitungen / Tutorials / Dokumentation, die nicht mal annäherungsweise dem aktuellen Stand der Software entsprechen? Einmal geschriebene Dokumentation muss gepflegt werden! Falsche Dokumentation ist in der Regel ein größerer Zeitfresser als nicht existente Dokumentation, insbesondere wenn die Änderungen nicht so gravierend sind, dass sie beim Lesen der Dokumentation nicht sofort auffallen.

Kurz gesagt: schreibt Dokumentation und haltet diese up-to-date.

Wer sich daran hält, wird wohl automatisch relativ schnell die goldene Mitte finden und weder zuviel Dokumentation schreiben (die später nicht aktualisiert wird) noch zu wenig (wenn man sich daran hält, dass man generell dokumentieren soll).

Zugegeben, dass ist jetzt relativ generell gehalten, aber DEN Königsweg wird es nicht geben (zumindest ist er mir noch nicht untergekommen). Dennoch habe ich noch ein paar Dinge zu diesem Punkt zu sagen:

  1. Dokumentation muss denen zugänglich sein, der sie benötigt. Wer ein Framework entwickelt und sämtliche Dokumentation auf seinem privaten Rechner hält (oder auch eben im Kopf), der muss sich nicht wundern, dass die Akzeptanz nicht sonderlich hoch sein wird, wenn andere Entwickler keinen Zugriff auf die Dokumentation haben.
  2. Dokumentation muss durchsuchbar sein. Wer sämtliche Dokumentation auf einem FTP-Server ablegt und Entwickler anhand des Dateinamen raten müssen, welches Dokument sie benötigen, verschwendet massiv Zeit (und somit Geld).
  3. Microsoft-Office Dokumente sind KEINE gute Wahl für Dokumentation. Zumindest nicht, wenn es sich bei dem Dokument um ein “Live-Dokument” handelt, an welchem noch gearbeitet wird. Alles was nicht in reiner Textform abgespeichert wird, lässt sich nur schwer bis gar nicht vergleichen (ja, ich weiß, dass Office mittlerweile Open XML kann, aber bis das Standard wird…). Und wenn jetzt die Dokumente noch auf einem Shared-Laufwerk liegen, muss nur irgendwer mal vergessen, ein Dokument zu schließen und verlässt dann am besten für längere Zeit seinen Arbeitsplatz. Und schon verschwendet man noch mehr Zeit, bis man Änderungen vornehmen kann.
  4. Verschiedene Versionen von Dokumenten sind auch immer sehr hilfreich (Achtung: Sarkasmus!). Wenn eine Schnittstellenbeschreibung sowohl als Word-, Excel als auch PDF-Dokument vorliegt, alle die gleiche Versionsnummer tragen und sich alle Dokumente inhaltlich unterscheiden… was machen Sie dann? Hoffentlich steht in einem solchen Fall am Anfang des Dokuments eine Historie, wo vermerkt ist, wer was geändert hat, so dass sie die entsprechenden Personen ansprechen können. Einen Document-Owner wird es in einer solchen Situation nicht geben (oder er hat seinen Job nicht getan). Fehlt auch eine Historie, dürfen Sie in mühsamer Kleinarbeit eigentlich das komplette Dokument hinterfragen / neu zusammenstellen oder ähnliches.
  5. Behalten Sie beim Schreiben von Dokumentation im Hinterkopf, wer die Zielgruppe ist. Mal angenommen, eine Applikation muss über’s Internet von außen auf dem Port 8080 erreichbar sein. Für einen Entwickler sollte diese Aussage genügen. Für einen Administrator sollte diese Aussage ebenfalls genügen. Für einen nicht-technischen Endanwender werden die Begriffe Port und Port-Forwarding sicherlich eine etwas ausführlichere Beschreibung benötigen.
    Ein Adminstrator, der eine Applikation nur auf der technischen Infrastruktur betreiben soll, wird es herzlich wenig interessieren, welche Design Patterns in der Applikation vorkommen. Dafür wird es ihn aber durchaus interessieren, wie eine Applikation zu deployen ist und welche Voraussetzungen gelten. Es wäre also äußerst unklug, Dokumentation so zu gestalten, dass der Leser viele, für ihn unnötige, Informationen erhält, weil diese innheralb eines Dokumentes oder gar über mehrere Dokumente verstreut sind.
    Überlegen Sie sich also, an wen sich die Dokumentation richtet! Mögliche Zielgruppen wären: Entwickler, Tester, Administratoren, Marketing, Endanwender.
    Überlegen Sie, welche Informationen für die jeweilige Zielgruppe relevant ist. Ein paar Stichwörter für die jeweiligen Gruppen soll dies verdeutlichen (wobei die Punkte der jeweiligen Vorgruppe in der Regel ihre Gültigkeit behalten):- Endanwender: Systemvoraussetzungen (welche Betriebssystem, welche JRE-Version, etc.), Installation, Benutzung.

    • Marketing: was sind die Key-Features / Alleinstellungsmerkmale? Warum ist das Produkt so toll? Was kann es besser als ein Konkurenzprodukt (und wenn es nur die Möglichkeit ist, die Hintergrundfarbe zu ändern)?
    • Administratoren: Systemvoraussetzungen (JRE, ggf. Server, Datenbank, Schreib-/Leserechte, Umgebungsvariablen, etc.), Installation, Wartung (wo befinden sich z.B. Log-Dateien)
    • Tester: welches Verhalten wird von einer Funktionalität erwartet? Gibt es unter Umständen einen Debug-Modus, welcher der Applikation mehr Informationen entlockt, als sie dem Endanwender zeigen soll?
    • Entwickler: Überblick über die Systemarchitektur, Programmierrichtlinien, verwendete Werkzeuge (inkl. Versionsnummer), Übersicht über vorhandene Systeme (Versionskontrollsysteme, Bugtracker, Datenbanken, Test-Server, etc), Deployment-Guide (welche Schritte sind bei einem neuen Release zu beachten, z.B. Versionsnummer hochsetzen, Changelog veröffentlichen, etc.)
      • Im Idealfall kann ein neuer Entwickler in Ihrem Team mit nur einem Startdokument alleine gelassen werden, mit dessen Hilfe er seinen kompletten Arbeitsplatz einrichten kann (verwendete Werkzeuge aufsetzen, etc.), das Projekt aus dem Versionskontrollsystem auschecken kann, dieses builden, deployen sowie Änderungen einbauen kann, ohne alle zwei Minuten nachfragen zu müssen. Wie gesagt: im Idealfall.
  6. Dokumentieren Sie wiederkehrende Probleme / Aufgaben und deren Lösung! Wenn Sie zum Beispiel alle zwei Monate ihren Continious Integration Server aktualisieren, weil fast jede Woche ein neues Release herauskommt (ist bei Hudson wirklich so) und Sie jedes Mal in einer Konfigurationsdatei einen bestimmte Eintrag ändern müssen, so dokumentieren sie dies. Zwar bleiben solche Aufgaben in der Regel an einer Person hängen, die die entsprechenden Fallstricke irgendwann kennt, aber wenn die Aufgabe doch einmal von einer anderen Person erledigt werden muss, so kann man sich viel Zeit und Nerven sparen, wenn man nur eine (fehlerfreie) Checkliste abarbeiten muss.
    Unter diesem Punkt könnte man unter Umständen auch “Zugangsdaten” anführen. Wie häufig sitze ich vor einem Login für einen Test-Server und habe mal wieder das Passwort vergessen, weil ich das nicht so häufig benötige? Natürlich sollten Sie nicht unbedingt die Zugangsdaten zu Ihrem Produktionssystem der ganzen Firma zur Verfügung stellen. Aber Test-Systeme zu denen eh jeder Zugang hat respektive erhält, sollten ruhig dokumentiert sein.
  7. Abkürzungen und domänenspezifisches Fachvokabular gehören dokumentiert! Ebenso Begriffe, die nicht eindeutig in einem Kontext sein müssen. Stellen Sie sich vor, eBay würde den Begriff “Kunde” in seinen Sourcen verwenden. Sind damit Käufer, Verkäufer oder beide gemeint? Noch schlimmer wäre es, wenn der Begriff “User” verwendet werden würde, dann würden da noch Administratoren, Moderatoren und ggf. sogar nicht angemeldete Besucher zu zählen. Häufig fehlt ein solches Dokument in Firmen, was Neulinge auf einen Gebiet, erst einmal nur Bahnhof verstehen lässt. Tragen Sie Sorge dafür, dass in ihren Sourcen Begrifflichkeiten nicht doppeldeutig sind und nicht unbedingt bekannte Begriffe erklärt werden. Wie und wo ist nebensächlich, wenn sich etwas etabliert hat. Ob Sie nun ein Wiki, ein Word-Dokument oder eine Datei direkt im Projekt anlegen spielt keine Rolle, solange es eine bekannte zentrale Anlaufstelle bei Begriffsschwierigkeiten gibt.
  8. Wählen Sie als Sprache etwas, was die Mehrheit im Team kann. Dies wird in der Regel deutsch oder englisch sein. Ein paar Punkte, die bei der Sprachauswahl beachtet werden sollten:
    • wie hoch ist die Wahrscheinlichkeit, dass das Projekt “internationale Unterstützung” erfährt. Sei es durch ein weiteres Team aus einer ausländischen Niederlassung, Outsourcing oder nur ein Austauschstudent, der sein Praktikum bei Ihnen in der Firma abhält.
    • wie hoch ist die Wahrscheinlichkeit, dass das Projekt Open Source wird? Wenn darauf spekuliert wird, eine Entwicklergemeinde um ein Projekt herum aufzubauen, sollten Sie auch möglichst vielen Entwicklern zumindest die Chance lassen, sich richtig in Ihr Projekt einzuarbeiten
    • beherrscht jeder die Sprache so halbwegs? Wenn die Dokumentation auf englisch verfasst wird und sich diese so liest, wie Öttinger spricht, dann brauchen Sie gar nicht dokumentieren. Das tut sich niemand freiwillig an!
  9. Anspielungen und Fantasiewörter sollten vermieden werden. Während zum Zeitpunkt des Schreibens ggf. noch etliche Menschen die Anspielung auf Öttinger verstanden haben, wird sich in fünf Jahren keiner mehr daran erinnern können (und zwar an dieses nette Video: http://www.youtube.com/watch?v=ge4hFFLtEIM). Wenn in der Dokumentation Bezug auf einen Running-Gag im Büro genommen wird, lockert das unter Umständen die Dokumentation auf, wirft bei nicht Eingeweihten aber Fragen auf. Wieder gilt: behalten Sie die Zielgruppe im Hinterkopf. “Foobar”, “42”, “640 kb should be enough”, “Alice und Bob” oder zum Beispiel die Frage ob “lieber die rote oder blaue Pille” werden unter Entwicklern in der Regel verstanden. Aber setzen Sie nicht zuviel voraus. Mein Lieblingsbeispiel wäre “db 0x723 ; RIPLVB”. Wer es nicht kennt, sollte das Buch Code Complete von Steve McConnell bestellen, welches sein Gewicht in Gold wert ist (oder eben kurz Google verwenden, wer das Buch schon zu Hause hat ;-) Oder was mir vor kurzem passiert ist: ich habe bei der Überprüfung von Wertepaaren eine CastorPolluxException geworfen, wenn einer der beiden Werte fehlte. Die Zahl der Entwickler die mit Castor und Pollux nichts anfangen konnten, war weitaus höher, als die eine Person, die die Wortwahl einzuordnen wusste.
  10. Lassen Sie mit Hilfe eines Tools überprüfen, wie es um Ihre (Source-)Dokumentation bestellt ist. In der Java-Welt bietet sich Checkstyle an. An dieser Stelle passt dann auch eine kleine Bitte an alle Java-Entwickler dieser Welt: wenn ihr schon JavaDocs schreibt, so schließt den ersten Satz mit einem Punkt ab! Ansonsten wird keine Zusammenfassung in der JavaDoc-Übersicht angezeigt.
    Aber verlassen Sie sich nicht auf diese Tools. Sie könnten auch in jeden JavaDoc “Blub.” schreiben und dennoch würde Ihnen Checkstyle hervoragende Arbeit bescheinigen.
    Dazu eine kurze Anmerkung: Checkstyle zeigt für den aktuellen tilto-Sourcecode eine 100%ige Kommentar-Abdeckung an. Sobald ich aber in eins der JSP-Fragmente muss, graut es mir. Da befinden sich nämlich leider nur äußerst spärlich Kommentare.
  11. Backups werden doch eh schon gemacht, oder? ;-)
  12. Dokumentieren Sie die wichtigen Sachen! Hier schließt sich der Kreis, denn eigentlich beinhaltet Punkt 1 diese Aussage schon implizit. Weil der Punkt aber so wichtig ist, nochmal explizit: dokumentieren Sie kritische Stellen. Wer schon mal vor einem regulärem Ausdruck in einem Perl-Source den Kommentar “Ab hier wird’s schmutzig, viel Spass…” gelesen hat und sonst nichts weiter an Kommentaren vorfindet, weiß, auf wieviel Dokumentation man zu verzichten bereit ist, wenn dadurch die wirklich wichtigen Stellen erläutert werden.
    Dokumentieren Sie auch Entscheidungen, zu denen offensichtlich weitere Alternativen in Betracht kämen, warum man diesen Weg gewählt hat und nicht eine der Alternativen.

Zusammenfassung
Dokumentation ist wichtig! Der Artikel ist zwar länger geworden als ursprünglich geplant, dennoch gibt er nur ein paar Denkanstöße. Sicherlich würde sich noch mehr zu diesem Thema an dieser Stelle sagen lassen, aber wer mehr über die Thematik lesen möchte, sollte mal nach “how to write good documentation” googeln. Dort findet man genügend Artikel, die teilweise recht ausführlich sind und teils andere Schwerpunkte aufweisen. Durch den jeweils anderen Blickwinkel lassen sich dann auch durchaus konträre Meinungen finden. Aber machen Sie sich selbst ein Bild.

Ausblick
Im nächsten Artikel geht es um ein verwandtes Problem: “Package- und Verzeichnis-Namen

4 Gedanken zu „Softwareentwicklung im Team – Teil 4 – Dokumentation“

Hinterlasse eine Antwort

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind markiert *

Du kannst folgende HTML-Tags benutzen: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>