Agilität und Dokumentation – ein Gegensatz?

Ich bin gelegent­lich als Auditor für Softwareentwicklungs-Pro­jekte unter­wegs. Wenn ich agile Pro­jekte re­viewe, dann finde ich häufig die hier über­spitzt dar­ge­stellte Ein­stellung:

Wir sind agil. Wir doku­men­tie­ren doch nix. Der Wissens­transport über direkte Kom­mu­ni­ka­tion ist doch viel effizienter.

Wir machen Clean Code. Da braucht man keine Quell­code-Kom­men­ta­re. Der Code kann ge­lesen werden und sagt immer die Wahr­heit.

Dieser Stand­punkt kommt mir jedes­mal wieder als sehr dog­ma­tisch vor­ge­tra­genes Credo ent­gegen. Hier hat sich bei mir der Ein­druck ver­festigt, dass eine Aus­sage aus dem agilen Mani­fest nur zu gerne als Aus­rede ge­nom­men wird, um nicht doku­men­tie­ren zu müssen.

Inhalt

• Dokumentation ist bei agilen Vor­gehens­weise nicht ver­boten
• Code beschreibt das „Wie“ und nicht das „Warum“
• Effiziente Doku­men­ta­tion – aller Anfang ist… einfach
• Mache alles mehrfach!
• Fazit

Dokumentation ist bei agilen Vor­gehens­weise nicht ver­boten

Sehen wir uns zu­erst noch einmal das Agile Mani­fest an. Dort gibt es den Wert:

Funktionierende Soft­ware mehr als um­fas­sende Doku­men­tation

Da steht wirklich „mehr als“. Damit wird funk­ti­onie­rende Soft­ware wichtiger an­ge­sehen als um­fas­sende Doku­men­ta­tion. Da steht nicht, dass Doku­men­ta­tion weg­ge­lassen werden soll. Das kann ich auch ver­stehen und unter­stützen: Was nützt eine um­fassende Doku­men­ta­tion, wenn die Soft­ware nicht funktioniert?

Ich habe auch schon Pro­jekte be­obachtet, die mit einer Doku­men­ta­tions­orgie ge­startet sind. Nach fünf Jahren Fach­kon­zeptions­phase lagen dann viele hunderte Seiten Doku­men­ta­tion vor. Der Kunde hat sich das an­ge­sehen und das Pro­jekt dann ein­ge­stellt, weil die penibel doku­men­tier­ten An­for­de­rungen schon lange wieder über­holt waren. Zu­ge­geben, das war auch kein agiles Projekt.

Auf der anderen Seite stellt sich die Frage, was eine Soft­ware nützt, die nach einiger Zeit nie­mand mehr ver­steht? In den zwölf Prin­zipien finden wir dazu:

Die effizienteste und effektivste Methode, In­for­ma­ti­onen an und inner­halb eines Ent­wicklungs­teams zu über­mitteln, ist im Ge­spräch von An­ge­sicht zu Angesicht.

Das ist ver­ständlich und dem kann ich sofort zu­stim­men. Da­mit stellt sich aller­dings die Frage, wozu Doku­men­ta­tion dienen soll? Doku­men­ta­tion dient nach dem gerade Ge­sagten nicht dazu, die Kom­muni­ka­tion in einem Ent­wick­lungs­team zu er­setzen. Das ist aber nur der Blick auf eine relativ kurze Zeit­spanne im Lebens­zyklus von Software.

Die meiste Zeit ist Soft­ware in Be­trieb und Weiter­ent­wick­lung. damit gibt es dann in den meisten Fällen kein Ent­wick­lungs­team mehr. Damit geht das Prinzip dann einfa­ch ins Leere:

• Ich habe öfter gesehen, dass eine Applikation sehr lange gelebt hat und über Jahre oder Jahrzehnte von verschiedenen Entwicklerteams erweitert und umgebaut worden ist. Woher bekommt ein neues Team die benötigten Informationen?
• Ich habe es erlebt, dass selbst der Fach­bereich nicht mehr genau wusste, was eine App­li­ka­tion macht. Wie soll man da eine Ab­lösung hinbekommen?
  
  

Code beschreibt das „Wie“ und nicht das „Warum“

In Zusammen­hang mit agiler Ent­wick­lung wird oft auch „Clean Code“ [1] heran­ge­zogen. Hier ist die Argu­men­ta­tions­linie eher, dass Doku­men­ta­tion ver­altet, wenn sie nicht ge­pflegt wird und dann schlimmer ist als über­haupt keine Doku­men­ta­tion. Den Effekt kenne ich. Aller­dings ist meine Schluss­folge­rung eine andere. An­statt Doku­men­ta­tion über Bord zu werfen, muss sie aktu­ell ge­halten werden.

Das Gleiche gilt bei­spiels­weise auch für Test­fälle. Auch hier habe ich schon er­lebt, dass Test­fälle ein­fach ge­löscht wurden, wenn sie nicht mehr „grün“ sind, an­statt sie auf einem aktuellen Stand zu halten. Auch das ist kontra­produktiv.

Die ver­meindliche Quelle der Wahr­heit soll im Code liegen. Wenn man nach den Prin­zi­pien von Clean Code vor­geht, dann wird der Code les­bar. Das ist in jedem Fall wahr. Aller­dings kann ich im Code nur lesen, wie etwas ge­macht wird. Damit weiß ich noch lange nicht, warum etwas so ge­macht wird.

Es gibt in der Ent­wicklung einer Appli­ka­tion oft­mals Design-Ent­schei­dungen, die ge­troffen werden müssen. Oft­mals gibt es keine kon­kreten An­for­de­rungen, sodass die Aus­wahl unter den zur Ver­fügung stehen­den Alter­na­ti­ven mehr oder weniger zu­fällig ge­schehen kann. Wenn man jetzt im Nach­hinein ver­sucht, die Gründe für eine Design-Ent­schei­dung zu re­kon­struieren, so funk­tio­niert das oft­mals nicht mehr. Bei einer Er­weite­rung oder einem Um­bau der Soft­ware ist mann dann leider ge­zwungen, diese un­er­klär­lichen Ef­fekte als ge­fordert zu be­han­deln und un­ver­ändert zu lassen. Ver­besserungs­poten­ziale werden da­mit ver­schwen­det. Das geht am Ende so weit, dass Soft­ware neu ge­baut wird, nur weil die alte Soft­ware nicht mehr aus­reichend ver­standen wird – etwas das ich leider auch schon er­lebt habe.

Effiziente Doku­men­ta­tion – aller Anfang ist… einfach

Ein be­liebtes Ar­gu­ment für das Weg­las­sen von Doku­men­ta­tion ist das ver­meind­liche Ein­spar­poten­zial. Be­trach­ten wir das Bei­spiel Java und die dort so be­liebten Getter und Setter. Zu­ge­ge­bener­maßen ist die Doku­men­ta­tion von Gettern und Settern nicht sehr span­nend. Auf der anderen Seite kostet sie aber auch so gut wie nichts.

Getter und Setter sollten nicht manu­ell ge­schrie­ben werden. Statt dessen werden sie von der IDE (bei­spiels­weise Eclipse) auf Knopf­druck auto­ma­tisch er­stellt. Dazu sind in der IDE Tem­plates hin­ter­legt, die auch die Doku­men­ta­tion mit er­stellen können. Das Ein­spar­poten­zial ist also die Er­stellung und Ein­bindung der Tem­plates. Wenn man nicht gerade das aller­erste Pro­jekt macht, dann hat man solche Tem­plates schon, so­dass sich die Ein­sparung im Minuten­bereich bewegt – und das nur ein­malig. Das ist also nicht wirk­lich der Rede wert.

Das Gleiche gilt auch für andere, wieder­kehrende Auf­gaben, wie die Er­stel­lung von Kon­struk­toren, De­struk­toren oder De­le­gates. Also die Er­stel­lung von „un­span­nen­den“ Kom­mentaren be­kommt man quasi ge­schenkt. Es spricht also nichts da­für, diese ein­sparen zu wollen.

Bei anderen Kom­men­taren muss man sich schon etwas Mühe geben. Das ist es aber auch Wert. Wenn sich etwas nicht un­mittelbar er­schließt, sollte das „Warum“ in einem Kom­men­tar ver­ewigt werden.

Mache alles mehrfach!

Am Ende gibt es aber ein Argu­ment, das ich für mich als das wich­tig­ste iden­ti­fi­ziert habe. Auch und ge­rade bei agilen Pro­jekten darf die Qualität nicht „ein­ge­spart“ werden. Bei sicher­heits­kritischen Sys­tem, wie bei­spiels­weise denen im Flug­zeug, führt das dazu, dass Kom­po­nen­ten drei­fach aus­ge­legt werden. Auf die Soft­ware-Ent­wick­lung über­tragen be­deutet das, dass es sinn­voll sein kann, Dinge mehr­fach zu machen. Da­durch werden unter­schied­liche Blick­winkel aus­ge­leuch­tet und es fällt Fehlern schwerer, sich zu verstecken.

Nun sind wir es in der Soft­ware-Ent­wicklung schon ge­wohnt, Dinge mehr­fach zu durch­denken: Spezi­fi­ka­tion, Pro­gram­mieren, Testen. In diesen Ka­non passt die Do­ku­men­ta­tion. Dies gilt ins­be­son­dere, wenn im Rahmen von agiler Ent­wicklung die klas­sische Spezi­fi­ka­tion deut­lich an Be­deutung verliert.

Fazit

Mir ist schon passiert, dass ich beim Doku­men­tie­ren über Fälle nach­ge­dacht habe, die vor­her nie auf­ge­taucht waren. Das ist im Sinne der Quali­tät sicher posi­tiv. Mir ist die Quali­tät wich­tig, und sei es nur, dass nie­mand mir nach­sagen kann, ich hätte schlampig ge­arbei­tet. Des­halb halte ich Doku­men­ta­tion für einen wich­tigen Be­stand­teil der Soft­ware-Ent­wick­lung, der auch in einem agilen Kon­text seine Be­deu­tung nicht verliert.

Noch Fragen?

Wie können Sie agile Methoden in Ihrer Organisation umsetzen, damit sie einen echten Mehrwert liefern? Erfahren Sie, wie wir Sie unterstützen können:

Dr. Gerd Neugebauer - ist Senior IT-Architekt mit Leib und Seele – und davon gibt es nicht wenig. Er ist insbesondere auch im Web- und Portal-Umfeld seit vielen Jahren tätig. Aus Erfahrungen mit vielen Kundenprojekten heraus gespeist ist sein Interesse an Vorgehensmodellen für die Durchführung von IT-Projekten.

Referenzen