- 2 -nikation’, ‚umfassende Partizipation’ und ‚öffentliche Präsentation’ zur Effizienzsteige-rung eingesetzt werden. Diese Maßnahmen decken dann die Gründe ab, aus denen schriftliche Dokumentation erstellt worden wäre. Eine determinierende Wirkung ist beispielsweise bei hohen Sicherheitsanforderungen an Software gegeben. In diesem Fall kann nicht ohne weiteres auf schriftliche Dokumentation verzichtet werden. Verschie-dene Faktoren können dabei Einflüsse auf (1) die Entwicklerdokumentation selber, auf (2) vorgestellt Maßnahmen zur Effizienzsteigerung der Dokumentation und auf (3) die Wirkung verschiedener Maßnahmen haben.

Zusammenfassend lässt sich feststellen, dass Entwicklerdokumentation effizienter gestaltet werden kann. Man muss jedoch bei einer Gestaltung die Umwelt und Situation, in der die Softwareentwicklung und das Anwendungsgebiet der Software eingebettet sind, beachten.

Kai Oey

Diplomarbeit

im Fach Management der Softwareentwicklung

Dokumentation in der Softwareentwicklung

Effizienter Einsatz von Entwicklerdokumentation

Vorgelegt in der Diplomprüfung im Studiengang Wirtschaftsinformatik der Wirtschafts- und Sozialwissenschaftlichen Fakultät der Universität zu Köln.

Köln, im September 2002

II

Dokumentation ist nicht Teil der Lösung, sondern Teil des Problems.

Tom DeMarco („Wien wartet auf Dich“, S. 130)

Für meine Eltern

III

Inhaltsverzeichnis

Inhaltsverzeichnis   III

Abk  ürzungsverzeichnis  V

Abbildungsverzeichnis   VI

1  Einleitung  1

1.1  Problemstellung  2

1.2  Einordnung und Ziel der Arbeit  3

1.3  Vorgehensweise  4

1.4  Erläuterung verwendeter Begriffe  5

2  Entwicklerdokumentation  9

2.1  Gegenstände der Entwicklerdokumentation  9

2.2  Gründe für Entwicklerdokumentation  12

2.2.1  Wissenskonservierung  12

2.2.2  Wissenstransfer  13

2.2.3  Koordination  14

2.2.4  Kommunikation  15

2.2.5  Softwareerstellungs-Vertrag  15

2.2.6  Organisatorische Politik und Macht  16

2.2.7  Strukturierung der Implementierung  17

2.2.8  Durchdringung inhaltlicher Konzepte  17

2.2.9  Geforderte Qualitätsstandards  18

2.2.10  Dokumentationsvorgaben  18

2.3  Nachteile von Entwicklerdokumentation  19

2.3.1  Aktualität  19

2.3.2  Aktualisierungsaufwand  20

2.3.3  Verständlichkeit  21

2.3.4  Informationsfindung  21

2.3.5  Zusätzlicher Ressourcenbedarf  22

2.3.6  Motivationsproblem  22

3  Effizienzsteigerung des Einsatzes von Entwicklerdokumentation  24

3.1  Effizienz von Entwicklerdokumentation  24

3.2  Maßnahmen zur Effizienzsteigerung  27

3.2.1  Grundkonzepte und Qualitätsanforderungen  28

3.2.2  Quantitative Aspekte  36

3.2.3  Alternativen zu traditionellen Ansätzen der Dokumentation  42

3.3  Kritische Beleuchtung weiterer und genannter Vorschläge  53

3.3.1  Zeitpunkt von Dokumentation  53

3.3.2  Technische Hilfsmittel  54

3.3.3  Video- und Audioaufnahmen als Dokumentation  55

3.3.4  Kompletter Dokumentationsverzicht  56

3.3.5  Positive Aspekte von Redundanzen  56

3.3.6  Unnötigkeit richtiger und aktueller Dokumentation  56

3.3.7  Teamgröße und angemessene direkte Kommunikation  57

3.3.8  Öffentliche Präsentation und Prozessdokumentation  57

4  Einflussfaktoren auf Entwicklerdokumentation  58

4.1  Organisatorische Einflussfaktoren  58

IV

4.1.1  Ablauforganisation  59

4.1.2  Aufbauorganisation  59

4.1.3  Umfang eines Projekts  60

4.1.4  Zeitraum der Erstellung eines Projektes  61

4.1.5  Fluktuation  62

4.1.6  Arbeitsteilung  62

4.1.7  Planung und Kontrolle  63

4.1.8  Entscheidungsdelegation  64

4.1.9  Vorauskoordination  65

4.1.10  Formalisierung  65

4.2  Softwarespezifische Einflussfaktoren  66

4.2.1  Art der Auslösung  66

4.2.2  Unklarheit der Entwicklungsaufgabe  67

4.2.3  Dynamik der Anforderungen  68

4.2.4  Neuartigkeit der Technologie  69

4.2.5  Intensität der Kunden-/Marktkommunikation  69

4.2.6  Sicherheitsanforderungen der Software  69

4.2.7  Lebensdauer von Entwicklerdokumentation und Software  70

4.2.8  Vorgehensmodelle  71

4.3  Weitere Einflussfaktoren  72

4.3.1  Verhalten der Mitarbeiter  72

4.3.2  Ausbildung und Wissen der Mitarbeiter  72

4.3.3  Technische Unterstützung der Entwicklung  73

4.3.4  Wirtschaftlicher Druck auf Software-Firmen  74

5  Schlussbetrachtung  75

6  Literaturverzeichnis  76

7  Anhang A: Literatur zu Formatierungsvorschlägen von Code und  

Kommentaren   92

V

Abkürzungsverzeichnis

CASE Computer Aided Software Engineering

CMM Capability Maturity Modell

DIN Deutsches Institut für Normung e. V.

ISO International Standardisation Organisation

NASA National Aeronautics ans Space Administration

XP Extreme Programming

VI

Abbildungsverzeichnis   

Abb.  1-1: Schematische Darstellung der Vorgehensweise.  

Abb  3-1: Effektivität von Kommunikationsalternativen  

1

1 Einleitung

Dokumentation ist in der Softwareentwicklung ein geläufiges Stichwort. Sie ist Be-standteil jeder Software. ¹ Zu den Aufgaben eines Programmierers gehört es Entwicklerdokumentation ² zu erstellen. ³ Sie „ (...) dient der Aufzeichnung von Informationen über die Prozesse und Produkte der Entwicklung.“ 4

Entwicklerdokumentation wird verschieden gehandhabt und bewertet. Einerseits wird sie in der Softwareentwicklung als absolut notwendig erachtet und sogar postuliert, je mehr in einem Softwareentwicklungsprojekt dokumentiert wird, desto „besser“ ist dies für ein Projekt. ⁵ Diesem Verständnis liegen zum Beispiel Vorgehensmodelle, wie das CMM, das V-Modell oder auch die ISO 9000, zugrunde. 6

Andererseits wird Entwicklerdokumentation in den Hintergrund gestellt, als hinderlich für ein erfolgreiches Softwareprojekt angesehen und soweit wie möglich reduziert. ⁷ In der Praxis kann häufig beobachtet werden, dass Entwicklerdokumentation, selbst bei erfolgreichen Softwareentwicklungen, als lästig angesehen und vernachlässigt oder teilweise weggelassen wird. ⁸ Von Dokumentationsvorgaben wird häufig abgewichen und erstellte Entwicklerdokumentation wird als mangelhaft bewertet. 9

¹ Vgl. Boehm u.a. /Characteristics/ S. 2.1-2.2; Ambler /Agile Modeling/ S. 4

² Vgl. zur Abgrenzung Kapitel 1.4

³ Vgl. Komarnicki /Programmiermethodik/ S. 136

⁴ Stelzer /Möglichkeiten/ S. 104

⁵ Vgl. Borchert /Entwicklung/ S. 6-8; Visconti, Cook /Evolution/; Stelzer /Möglichkeiten/ S. 212-214; Block geht zwar nicht explizit davon aus, ihr Artikel Block /Life Cycle/ lässt dies aber vermuten

⁶ Vgl. Stelzer /Möglichkeiten/ S. 8-9; David /Relevanz/ S. 71; In der Praxis werden die Dokumentations-anforderungen der Vorgehensmodelle oft als Problem bezeichnet, vgl. Stelzer /Möglichkeiten/ S.

280

⁷ Vgl. Boehm /Agile Methods/ S. 66; Poppendieck /Lean Programming/ S. 3-4; Ambler /Agile Modeling/ S. 17

⁸ Vgl. David /Relevanz/ S. 18; Andersen u.a. /Systems Developement/ S. 159; Powell, French, Knight /Software Documentation/ S. 201; Brooks /Mythos/ S. 153; Wong /Incomplete Documentation/ S.

68

⁹ Vgl. Deifel u.a. /Praxis/ S. 31; Borchart /Entwicklung/ S. 6; Didrich, Klein /Aragmatic Approach/ S. 1; Visconti, Cook /Evolution/ S. 223; David /Relevanz/ S. 15-19

2

Entwicklerdokumentation hat sich jedoch für Beteiligte an einem Entwicklungsprojekt als hilfreiches Mittel zur Arbeitsunterstützung herausgestellt. ¹⁰ Aus diesem Grund wird die Entwicklerdokumentation auch als ein „notwendiges Übel“ ¹¹ bezeichnet.

Es existieren verschiedene Ansätzen zur Softwareentwicklung, mit jeweils verschieden stark ausgeprägten Anweisungen und Gestaltungsvorgaben zur Erstellung von Entwicklerdokumentation. ¹² Daraus lässt sich schließen, dass verschiedene Aspekte bei der Bestimmung eines effizienten Grades der eingesetzten Entwicklerdokumentation von Bedeutung sind. Deshalb lassen sich unterschiedliche Gestaltungsalternativen in Bezug auf die Erstellung von Entwicklerdokumentation finden.

Die Softwarebranche ist ein stark umkämpfter Markt. Um Wettbewerbsvorteile erreichen zu können ist es wichtig, die Softwareentwicklung so effizient wie möglich zu gestalten und Software auf hohem qualitativem Niveau zu erstellen. Doch die eine „silberne Kugel“ ¹³ , welche die Softwarekosten zur Erstellung qualitativ guter Software reduziert, ist nicht in Sicht. ¹⁴ Aus diesem Grund kann sich nur in kleinen Schritten einer effizienten Softwareentwicklung genähert werden. ¹⁵ Entwicklerdokumentation ist ein ‚Übel’ der Softwareentwicklung und deren Effizienzsteigerung einer der kleinen Schritte, die angegangen werden müssen, um Software effizienter zu erstellen. 16

1.1 Problemstellung

In der Theorie ist die Bedeutung der Entwicklerdokumentation unter verschiedenen Ausprägungen von Softwareprojekten noch nicht vollständig erfasst und die Meinungen über den Umfang notwendiger Entwicklerdokumentation gehen auseinander. Erschwert wird die Situation durch einen schwierigen Effizienzvergleich aufgrund der Uneinheit-

¹⁰ Vgl.Zokaites /Code/ S. 1-2 ; Cockburn /Development/ S. 176-177; Tempel /Re-Engineering/ S. 223

¹¹ Vgl. Komarnicki /Programmiermethodik/ S. 136; Ambler /Agile Modeling/ S. 144; Brooks und Naur nennen Dokumentation eine „Last“ (“a burden”), vgl. Brooks /Mythos/ S. 153; Naur /Computing/ S.

352

¹² Boehm u.a. unterstellen der Softwareentwicklung z.B. einen linearen Prozess, dessen Phasen durch eine strenge Dokumentation abgeschlossen wird, vgl. Boehm u.a. /Characteristics/ 2.1-2.9, wohinge-

gen dem Extreme Programming teilweise unterstellt wird, es verbiete Dokumentation außerhalb von

Quellcode, vgl. Paulk /Extreme Programming/ S. 22

¹³ Brooks /Silver Bullet/ S. 10

¹⁴ Vgl. Brooks /Silver Bullet/ S. 10

¹⁵ Vgl. Yourdon /Programmierkunst/ S. 30

¹⁶ Vgl. Smith, Thomas, Tilley /Documentation/ S. 235; David /Relevanz/ S. 1

3

lichkeit von Softwareprojekten sowie einer schwierigen Kosten-/Nutzenanalyse von Entwicklerdokumentation. 17

Wie es für verschiedene Softwareprojekte nicht den einen ‚besten’ Prozess gibt, ¹⁸ existiert für verschiedene Softwareprojekte, teilweise für verschiedene Module innerhalb eines Projektes, nicht die eine ‚beste’ Dokumentationsvorgehensweise. Vielmehr existieren in der Praxis verschiedenartige Ausprägungen von Dokumentationsvorgaben und Entwicklerdokumentationen. 19

Die Frage nach der Effizienz der erstellten oder vorgeschlagenen Entwicklerdokumentation wird in der Literatur nicht gestellt. Beispielsweise wird oft versucht, das Problem ineffizienter und auch oft ineffektiver Entwicklerdokumentation durch eine Technisierung, und somit einer effizienteren Verwaltung, zu beheben. ²⁰ Ein Dokumentationsdefizit wird in der Literatur auch erkannt. So schreibt Gluchowski beispielsweise: „Zu beklagen bleibt an dieser Stelle, dass viele Erkenntnisse, die während der Systemgestaltung gewonnen werden, sich nur im implementierten System wiederspiegeln, nicht jedoch als dokumentiertes Wissen (...) vorliegen.“ ²¹ Im folgenden geht Gluchowski davon aus, dass möglichst alles dokumentiert werden sollte und versucht eine Referenzarchitektur für eine solche Entwicklerdokumentation herzuleiten. Die Effizienz der erstellten Entwicklerdokumentation betrachtet aber auch Gluchowski nicht.

1.2 Einordnung und Ziel der Arbeit

Die geringe theoretische Durchdringung im Bezug auf die Effizienz von Entwicklerdokumentation in Softwareentwicklungsprojekten soll als Anlass für die Arbeit genommen werden. Die Arbeit soll dazu beitragen, dieses Defizit zu verringern.

Ziel der Arbeit ist es, Maßnahmen aufzuzeigen, die zu einer Effizienzsteigerung der Entwicklerdokumentation führen und darzulegen, welchen Einflüssen Entwicklerdokumentation unterliegt. Vor dem Hintergrund der erläuterten Problematik verfolgt die Ar-

¹⁷ Vgl.David /Relevanz/ S. 18; Boehm /Agile Methods/ S. 68

¹⁸ Vgl. Oestereich u.a. /Objektorientierung/ S. 18

¹⁹ Vgl. Ambler /Agile Modeling/ S. 166-167

²⁰ Vgl. beispielsweise Powell, French, Knight /Software Documentation/; Zeihsel, Wittern /Dokumentation/ S. 28-30 oder David /Relevanz/

²¹ Gluchowski /Informationssysteme/ S. 1

4

beit drei Unterziele. Erstens sollen Anforderungen an eine effiziente Dokumentation aufgezeigt werden. Zweitens wird hergeleitet, unter welchen Umständen und unter Zuhilfenahme welcher Maßnahmen eine angemessene Entwicklerdokumentation erstellt werden kann. Drittens werden Einflussfaktoren mit ihrer Wirkung auf Entwicklerdokumentation vorgestellt. Die Diplomarbeit soll damit zum einen der Theorie die Grundlage zur Diskussion über Vorschläge zur Entwicklerdokumentation liefern und zum anderen der Praxis Hinweise zu einer effizienteren Entwicklerdokumentation geben.

Fokus der Arbeit ist die Art von Dokumentation, die den Entwicklern, während der (Weiter-)Entwicklung einer Software, Informationen liefert. Nicht betrachtet werden in der Arbeit alle Arten von Prozess- ²² und Programmdokumentation ²³ , die Ausprägungen syntaktischer Gestaltung von Dokumentation ²⁴ , die physische Speicherung von Dokumentation ²⁵ und Dokumentationsmanagement ²⁶ .

1.3 Vorgehensweise

Die Arbeit ist das Ergebnis eines Literaturstudiums. Im ersten Teil der Arbeit, den Kapiteln 2 und 3, wird der Fokus auf die Softwareentwicklung gelegt. Die Arbeit geht dabei im ersten Kapitel auf die Gegenstände, die Gründe für und die Nachteile von Entwicklerdokumentation ein. Als nächstes wird die Effizienz von Entwicklerdokumentation beleuchtet. Dazu wird in Kapitel 3 hinterfragt, was unter der Effizienz einer Entwicklerdokumentation verstanden werden kann und es werden Maßnahmen vorgestellt, die die Entwicklerdokumentation effizienter gestalten können.

Im nächsten Teil der Arbeit, dem Kapitel 4, wird die Umwelt, in der sich eine Softwareentwicklung befinden kann, betrachtet. Dabei wird ein kontingenztheoretischer Ansatz ²⁷ verfolgt. Da Softwareprojekte in unterschiedliche Umfelder eingebettet sind, lassen sich Faktoren finden, die zum ersten auf die Entwicklerdokumentation, zum zweiten auf die

²² Vgl. zur Abgrenzung und zu Literaturquellen zur Prozessdokumentation Kapitel 1.4

²³ Vgl. zur Abgrenzung und zu Literaturquellen zu Programmdokumentation Kapitel 1.4

²⁴ Zur Syntax verschiedener Dokumente bzw. Modellnotationen vgl. beispielsweise Balzert /Lehrbuch/, Rumbaugh u.a. /Modellieren/, Ferstl, Sinz /Grundlagen/ oder Raasch /Systementwicklung/; vgl. zu

allgemeiner Dokumentationssyntax Rupietta /Benutzerdokumentation/

²⁵ Zu Vorschlägen der physischen Speicherung/Ablage von Dokumenten vgl. beispielsweise Gluchowski /Informationssysteme/; Zeihsel /Produktweiterentwicklung/ S. 23-26

²⁶ zum Dokumentationsmanagement in Projekten vgl. Madauss /Projektmanagement/ S. 319-328

5

Maßnahmen zur Effizienzsteigerung der Entwicklerdokumentation und zum dritten auf die Wirkung dieser Maßnahmen Einfluss haben. Die Arbeit versucht abzuleiten, wie sich die Entwicklerdokumentation unter dem Einfluss erkannter Faktoren gestaltet ²⁸ und welche Maßnahmen unter sinnvoll zur Effizienzsteigerung eingesetzt werden können. 29

In Abb. 1-1 ist das Vorgehen mit Hinweis auf das jeweilige Kapitel schematisch dargestellt.

Abb. 1-1: Schematische Darstellung der Vorgehensweise

1.4 Erläuterung verwendeter Begriffe

In diesem Kapitel werden Begriffe erläutert, die für das Verständnis der Arbeit wichtig sind, unterschiedlich aufgefasst werden könnten und dadurch zu einem ungenauen Verständnis der Arbeit führen würden.

Klassisch ist Dokumentation das schriftliche Festhalten von Informationen zu einem bestimmten Gegenstand sowie das resultierende Ergebnis dieses Vorgangs. ³⁰ Dokumenta-

²⁷ Vgl.Kieser, Kubicek /Organisation/ S. 45-47; Schreyögg /Organisation/ S. 326-327

²⁸ Es werden demnach deterministische Eigenschaften von Einflussfaktoren auf Entwicklerdokumentation aufgezeigt.

²⁹ Dieser Teil der Arbeit basiert auf rein theoretischen Überlegungen und baut in Ihren Gestaltungsalternativen auf Kapitel 3 auf. Eine empirische Arbeit, die Einflussfaktoren auf Entwicklerdokumentati-

on systematisch untersucht, konnte nicht gefunden werden.

³⁰ Vgl. Rupietta /Benutzerdokumentation/ S. 15-16; Gaus /Dokumentationslehre/ S. 1-2; Klassische Do- kumentationen zu alltäglichen Gegenständen und zur Unterstützung einer Aktion sind beispielsweise

6

tion wird mit dem Ziel betrieben, relevante Informationen über den dokumentierten Ge-genstand ³¹ zu späteren Zeitpunkten verfügbar zu machen, um Aktionen auf oder mit dem dokumentierten Gegenstand ausführen zu können. Dieses Ziel kann jedoch auch durch nicht schriftliche Methoden erreicht werden. ³² Aus diesem Grund werden in dieser Arbeit unter dem Begriff Dokumentation alle vorgestellten Möglichkeiten, die Ziele klassischer Dokumentation zu erreichen, zusammengefasst. 33

In der Softwareentwicklung werden unter dem Begriff der Dokumentation im Allgemeinen Programmdokumentation ³⁴ , Prozessdokumentation und Entwicklerdokumentation subsummiert. 35

Unter der Programmdokumentation wird der Teil einer Softwaredokumentation ver-standen, der die Installation, Bedienung und Administration einer Software erklärt und als Teilprodukt mit in das endgültige Softwareprodukt einfließt. 36

Die Prozessdokumentation besteht aus Informationen, die den Entwicklungsprozess der Software betreffen, diesen steuern und gestalten. ³⁷ Die Prozessdokumentation kann bei-

Bedienungsanleitungen,ein Beispiel von Dokumentation zur Informationssuche im Alltag sind Bei-

packzettel zu Arzneimitteln.

³¹ Der zu dokumentierende Gegenstand kann ein Produkt oder ein Prozess der Softwareentwicklung sein, vgl. Stelzer /Möglichkeiten/ S. 104

³² Vgl. Kapitel 3.2.3

³³ Beispielsweise zählen darunter direkte Kommunikation, umfassende Partizipation, öffentliche Präsentation und die (klassische) schriftliche Dokumentation, vgl. für weitere Alternativen Kapitel 3.2. Mit

dieser Ansicht wird Kieser und Kubicek gefolgt, die eine synonyme Sichtweise auf Weisungen und

Programme vertreten: „Persönliche Weisungen können ebenso mündlich wie schriftlich erteilt wer-den, und Programme können gleichermaßen in Handbüchern wie im Bewusstsein der Organisati-

onsmitglieder ‚festgeschrieben’ sein“, Kieser, Kubicek /Organisation/ S. 104

³⁴ Manchmal auch Benutzerdokumentation, (Benutzer-)Handbuch oder Produktdokumentation genannt, vgl. Jamin /Lexikon/ S. 109; Chroust /Modelle/ S. 189; Stelzer /Möglichkeiten/ S. 101, 302

³⁵ Vgl. Oestereich u.a. /Objektorientierung/ S. 213; Savolainen /Perspectives/ S. 111-112; Dumke, Foltin /Softwareentwicklungskomplexität/ S. 84; Krause /Software-Erstellungsvertrag/ S. 5-6; David

/Relevanz/ S. 61-62; Stahlknecht, Hasenkamp /Wirtschaftsinformatik/ S. 323-324; Die Benennung

der einzelnen Dokumentationsarten ist teilweise unterschiedlich, läuft jedoch semantisch immer auf

einer der bzw. die genannten Dokumentationsarten hinaus.

³⁶ Vgl. Balzert /Entwicklung/ S. 49; Sommerville /Software/ S. 230; Rupietta /Benutzerdokumentation/S. 15-16; Dumke /Software Engineering/ S. 102; David /Relevanz/ S. 63-64; zur Vertiefung eignet sich

Rupietta /Benutzerdokumentation/; eine Norm findet sich beispielsweise in DIN /DIN 66230/; eine

kurze Zusammenfassung findet sich in David /Relevanz/ S. 93-105

³⁷ Vgl. David /Relevanz/ S. 64-65; weiterführend Lehner u.a. /Organisationslehre/ S. 511-522; Dumke /Software Engineering/ S. 183-207; Koreimann /Softwareentwicklung/ S. 249-351; Hopkins, Jernow

/Software Development Process/; für spezielle Dokumentation zur Projektkontrolle (die im Kontext

dieser Arbeit der Prozessdokumentation entspricht) vgl. Madauss /Projektmanagement/ S. 177-247;

7

spielsweise den Ressourceneinsatz zur Entwicklung, eine Meilensteinplanung, Versionsmanagement, Ablaufplanung und Konfigurationsmanagement umfassen. 38

Entwicklerdokumentation ist die Dokumentation, die den Entwicklern einer Software zur Unterstützung ihrer Tätigkeiten zur Verfügung steht und die zum großen Teil durch Entwickler erstellt wird. ³⁹ Entwicklerdokumentation ist der Teil der Dokumentation, der sich beispielsweise auf den Quellcode oder auf die Architektur/Struktur der entwickelten Software bezieht. ⁴⁰ Die Entwicklerdokumentation kann dabei einerseits eine determinierende ⁴¹ , andererseits eine deskriptive Funktion erfüllen. ⁴² Determinierende Entwicklerdokumentation gibt Vorgaben für Programmierer, wie die Software umgesetzt werden soll. ⁴³ Beispielsweise übernehmen Entwicklerdokumentationen eine determinierende Funktion, indem Modelle (Klassendiagramme, Datendiagramme), Architektur-oder Designpläne Vorgaben zur Erstellung der Software enthalten. ⁴⁴ Deskriptive Entwicklerdokumentation ist Information, die sich auf Teile des Quellcodes bezieht, darlegt, was die Aufgabe eines bestimmten Codeabschnitts ist, und detaillierter erklären kann, wie das Ziel im Code umgesetzt ist. Deskriptive Entwicklerdokumentation kann sich beispielsweise auf Module, Datenbankfelder, Funktionen ⁴⁵ oder auch wenige Zeilen Quellcode beziehen. ⁴⁶ Oft wird sie in direkter Nähe oder im dokumentierten Ge-

³⁸ Vgl.Lehner u.a. /Organisationslehre/ S. 518; David /Relevanz/ S. 106-115; oder allgemein Vorgehensmodelle zur Softwareentwicklung.

³⁹ Vgl. Brodbeck /SE-Projekte/ S. 58-59; David /Relevanz/ S. 43-44, 86-89; Stahlknecht, Hasenkamp /Wirtschaftsinformatik/ S. 324

⁴⁰ Vgl. Ambler /Agile Modeling/ S. 143; Dumke /Software Engineering/ S. 3-4

⁴¹ Teilweise auch ‚spezifizierend’ genannt, vgl. David /Relevanz/ S. 61-63

⁴² Vgl. Ambler /Agile Modeling/ S. 143-144; Krause /Software-Erstellungsvertrag/ S. 6; Oestereich u.a. nennen dies externe bzw. interne Sicht der Dokumentation, vgl. Oestereich u.a. /Objektorientierung/

S. 219-220; David /Relevanz/ S. 62-63

⁴³ Vgl. David /Relevanz/ S. 74-75; Ambler /Agile Modeling/ S. 9; Boehm nennt den determinierenden Einsatz von Dokumentation „Vorabdokumentation“ und erstellt diese, „um (...) Ziele und Pläne für

künftige Tätigkeiten der Softwareentwicklung zu definieren (...)“, vgl. Boehm /Software-Produktion/ S. 37-38; Müller nennt determinierende Dokumentation explizit „Projektvorgaben“, vgl.

Müller /Software-Engineering/ S. 49

⁴⁴ Vgl. Cockburn /Development/ S. 127-129

⁴⁵ Der Ausdruck Funktion wird anstelle der in der OO üblichen Bezeichnung Methode verwendet, um den Charakter des Quellcodes hervorzuheben und eine Abgrenzung zu möglichen Methodendoku-

mentationen verschiedener Prozessmodelle anzudeuten.

⁴⁶ Vgl. Oestereich /Objektorientierung/ S. 219

8

genstand der Software (beispielsweise bei Quellcode) festgehalten. ⁴⁷ Entwicklerdokumentation mit erklärendem Charakter unterstützt somit die Softwareentwickler bei der Erstellung, Fehlerbeseitigung und Wartung einer Software.

Die Arbeit beschränkt sich auf die Betrachtung von Entwicklerdokumentation. Eine Effizienzbetrachtung dieser ist für die Entwickler einer Software am interessantesten. An-forderungen an die Programmdokumentation sind gut erkannt und verstanden ⁴⁸ und die Einbeziehung der Prozessdokumentation hätte den Umfang der Arbeit um Weiten überschritten. ⁴⁹ Da sich die Arbeit auf Entwicklerdokumentation bezieht, wird die Bezeichnung ‚Dokumentation’ im Folgenden synonym zur ‚Entwicklerdokumentation’ verwendet. Nur, wo es einer besseren Abgrenzung oder Verständlichkeit dient, wird explizit ‚Entwicklerdokumentation’ geschrieben.

Unter der Lebensdauer einer Dokumentation wird die Zeitspanne verstanden, in der eine Dokumentation aktiv, erstellend oder nachfragend, genutzt wird. 50

Einige Begriffe, die mit Bezug zu Dokumentation genannt werden, wie beispielsweise Lastenheft, Systemdefinition oder Grobkonzept, sind nur schwer einzugrenzen und werden unterschiedlich in der Literatur benutzt. ⁵¹ Auf eine Eingrenzung der Begriffe wird hier verzichtet. Wichtig ist, dass die Inhalte eines Dokumentes abgegrenzt sind. Wie ein entsprechendes Dokument in einem Projekt genannt wird und ob verschiedene Gegenstände der Dokumentation darin zusammengefasst werden, sei jedem Projektteam überlassen.

⁴⁷ Häufig, insbesondere bei Quellcode, wird dann einfach nur von ‚Kommentaren’ geredet, vgl. Kernighan, Plauger /Elements/ S. 117-128

⁴⁸ Vgl. beispielsweise DIN /DIN 66230/, Gray, London /Programm-Dokumentation/ oder Rupietta /Benutzerdokumentation/

⁴⁹ Um einen Eindruck zu bekommen muss man nur die umfangreiche Literatur mit Bezug auf Prozessmodelle der Softwareentwicklung betrachten. Alleine Literatur zu den Themen CMM oder XP ist

schon sehr umfangreich.

⁵⁰ D.h. selbst wenn Dokumentation sogar gänzlich unkorrekt ist, aber noch genutzt wird ist sie noch nicht am Ende der Lebensdauer angekommen. Einige Autoren würden die Bezeichnung ‚Ende des Le-

benszyklus einer Dokumentation’ verwenden. Hier wird jedoch die Meinung vertreten, dass es kei-nen typischen Lebenszyklus (wie beispielsweise Erstellen, Nutzen, Warten) einer Software gibt.

Hier wird vielmehr die Meinung vertreten, dass Entwicklerdokumentation einer ständigen und

gleichzeitigen Erstellung, Nutzung und Wartung unterliegt. Der Begriff ‚Lebensdauer’ ist also präg-

nanter, als der Begriff ‚Lebenszyklus’.

⁵¹ Vgl. David /Relevanz/ S. 74

9

2 Entwicklerdokumentation

Entwicklerdokumentation wird in verschiedenen Softwareentwicklungsprojekten und innerhalb eines solchen Projektes von verschiedenen Beteiligten unterschiedlich eingesetzt. Grundlagen zur Erstellung von Entwicklerdokumentation, also die Gegenstände, Gründe und Nachteil, werden in diesem Kapitel hinterfragt.

Zuerst werden verschiedene Gegenstände der Softwareentwicklung betrachtet, die dokumentiert werden können und die dadurch auch ausschlaggebend für den Umfang einer projektweiten Dokumentation sind. Hier stellt sich also die Frage, was dokumentiert werden kann (Kapitel 2.1). Des weiteren können sich unterschiedliche Dokumentati-onsvorgaben aus der unterschiedlichen Wichtigkeit von Gründen zur Dokumentation herleiten lassen. Es stellt sich folglich die Frage, welche Gründe es für Dokumentation gibt (Kapitel 2.2). Und im Anschluss wird untersuchte, welche Gründe gegen Dokumentation in der Softwareentwicklung sprechen können (Kapitel 2.3).

2.1 Gegenstände der Entwicklerdokumentation

Ein Entwickler, der ein Programm warten muss, das nicht von ihm selbst erstellt wurde, benötigt einen Großteil seiner Zeit, um dieses Programm zu verstehen. ⁵² Zum Verstehen eines Programms ist eine effiziente Entwicklerdokumentation über verschiedene Gegenstände des Programms hilfreich.

Nach David gibt es eine Vielzahl von Gegenständen in der Softwareentwicklung deren Dokumentation notwendig ist: ⁵³ beispielsweise Anforderungen, Analysen, Feinentwürfe, User-Interfaces, Schnittstellen, Datenmodelle, Architekturen, Testfälle und Quellcode.

Im Folgenden werden typische Gegenstände vorgestellt, die bei der Erstellung von Software vorhanden sein können und deren Dokumentation zu einem besseren Verständnis einer Software beitragen kann. Dabei werden die verschiedenen möglichen Gegenstände teilweise auf einem hohem Level zusammengefasst.

⁵² Vgl. Kuhlmann /Qualitätsmodell/ S. 119; Gray, London /Programm-Dokumentation/ S. 12; Tempel geht von mehr als 50% aus, vgl. Tempel /Re-Engineering/ S. 218-219

⁵³ Vgl. Zum folgenden Absatz David /Relevanz/ 73-92; Für eine weit detailliertere und umfangreicherer Zusammenstellung vgl. Gray, London /Programm-Dokumentation/

10

• Anforderungen

Anforderungen stellen den Grundbaustein einer Software dar. ⁵⁴ Sie beschreiben, was eine Software leisten soll. Ohne die Anforderungen zumindest ansatzweise zu kennen, kann kein Programmierer Software erstellen.

• Spezifikationen

Spezifikationen sind detailliertere Ausformulierungen von Anforderungen und zur Koordination der Arbeit eines Programmierers notwendig. Aus diesem Grund wird häufig gefordert, Anforderungen und/oder Spezifikationen schriftlich zu dokumentieren. 55

• Architektur

Bei der hohen Komplexität heutiger Software ist eine stabile Architektur ⁵⁶ ein guter Ausgangspunkt zur Erstellung von guter Software und bietet einen Überblick über verwendete fachliche und technische Konzepte. Allerdings ist die Architektur, gerade bei langlebiger Software, nicht statisch. 57

• Quellcode

Quellcode, bzw. Quellcode-Blöcke, wie beispielsweise Funktionen, Module oder Klassen sind die einzelnen Anweisungen, die Aktionen einer Software erzeugen. Quellcode ist in der Regel sehr umfangreich und komplex. Dokumentiert werden kann Quellcode beispielsweise durch Kommentare direkt im Programmtext. 58

• Schnittstellen

Zur Interaktion zwischen den einzelnen Komponenten einer Software werden klar definierte Schnittstellen benötigt. ⁵⁹ Gerade durch moderne objektorientierte Programmierparadigmen, bei der eine hohe Kapselung und Modularisierung in der Sys-

⁵⁴ Vgl.Brooks /Mythos/ S. 54-55

⁵⁵ Vgl. DeMarco /Projektmanagement/ S. 65-66; Brooks /Mythos/ S. 54-55

⁵⁶ Vgl. weiterführend Bass, Clements, Kazman /Architecture/ insb. Kapitel 2 “What Is Software Architecture?” oder für eine umfassende Definitionssammlung o.V. /Software Architecture/

⁵⁷ Vgl. Kazman /Scenario/ S. 6

⁵⁸ Vgl. Ambler /Agile Modeling/ S. 143

⁵⁹ Vgl. Oestereich u.a. /Objektorientierung/ S. 23

11

tementwicklung vorliegt, ist dies elementar. Schnittstellen müssen dokumentiert sein, damit jeder Programmierer weiß, wie ein Modul zu nutzen ist. 60

• Modelle und Analysen

Modelle, beispielsweise Objekt- und Prozessmodelle, stellen unterschiedliche Sichten oder Perspektiven eines Systems dar. Analysen betrachten ein System unter bestimmten Aspekten und in unterschiedlichem Detaillierungsgrad. Beides sind eine Abstraktion bestimmter Bereiche des späteren Systems. ⁶¹ Um zu einem Verständnis über ein Modell oder eine Analyse zu gelangen kann es sinnvoll sein, eine schriftliche Dokumentation von Entwurfsentscheidungen und Designalternativen (die ver-worfen wurden) zu erstellen. 62

Dem Ansatz deskriptiver Dokumentation folgend, ⁶³ können Modelle auch Dokumentation sein, wie beispielsweise Modelle von Datenbanken oder Architekturen. Sie entstehen dabei vor dem Implementieren einer Software ⁶⁴ und sind zum Verständnis und der Implementierung einer Software notwendig. 65

• Testfälle

Testfälle beinhalten mindestens detaillierte Vorgehensanweisungen, was und wie ein Gegenstand getestet werden soll und welches Ergebnis erwartet wird. Testfälle sind notwendig, ⁶⁶ da jedes Softwaresystem getestet werden muss. ⁶⁷ In der Regel gibt es eine sehr große Menge von Testfällen, da sichergestellt werden soll, dass möglichst viele Anwendungsszenarien auch wirklich funktionieren. ⁶⁸ Um den Überblick über die Testfälle nicht zu verlieren, sollten diese dokumentiert werden.

• Richtlinien & Styleguides

Richtlinien und Styleguides, beispielsweise Standards, Konventionen, Muster,

⁶⁰ Vgl. Yourdon /Programmierkunst/. S. 186; Ein praxisnahes Negativ-Beispiel hierzu ist der Absturz einer Ariane 5 Trägerrakete am 4.Juni 1996, der durch einen fehlerhaften Prozeduraufruf zustande

kam. Vgl. dazu Gleick /Bug/; Lions /Ariane 5/

⁶¹ Vgl. Borchart /Entwicklung/ S. 6; Tempel /Re-Engineering/ S. 220

⁶² Vgl. Oestereich u.a. /Objektorientierung/ S. 220

⁶³ Vgl. Kapitel 1.4

⁶⁴ Modelle stellen dann determinierende Dokumentation dar, vgl. Kapitel 1.4

⁶⁵ Vgl. Ambler /Agile Modeling/ S. 143-144

⁶⁶ Vgl. Beck /Extreme Programming/ S. 45

⁶⁷ Vgl. Sommerville /Software/ S. 9-10

12

Checklisten oder Vorlagen, ⁶⁹ müssen selber wenig dokumentiert werden, stellen jedoch eine schriftliche Dokumentation von zu nutzenden Formulierungen und Formatierungen, etwa von Variablennamen, Schleifen und Blöcken, in Projekten dar. Richtlinien und Styleguides können durchaus Projekt-/Produktübergreifend (z.B. unternehmenseinheitlich) gültig sein.

2.2 Gründe für Entwicklerdokumentation

In der geläufigen Literatur werden zwei Argumente, die für Entwicklerdokumentationen sprechen, immer wieder hervorgehoben. ⁷⁰ Zum einen wird betont, dass die Einarbeitung neu zum Projekt stoßender Mitarbeiter in kürzerer Zeit und unter weniger Entwicklungskosten geschieht. Unter diesem Aspekt wird Dokumentation zur Konservierung von Wissen, um es zu einem späteren Zeitpunkt verfügbar zu haben, genutzt. Zum anderen wird argumentiert, dass bei fehlender Dokumentation die Gefahr besteht, Anforderungen wegen fehlendem Hintergrundwissens aus fachlicher und technischer Sicht falsch zu implementieren. Der Transfer von Wissen, um nicht von falschen Annahmen auszugehen, wird hier unterstützt.

Diese beiden sind jedoch nicht die einzigen Gründe, aus denen Entwicklerdokumentation erstellt werden soll. Im Folgenden sind diese und weitere Gründe für Entwicklerdokumentation, die in heutigen Softwareentwicklungsprojekten bestehen können, erläutert.

2.2.1 Wissenskonservierung

Schriftliche Dokumentation dient der Konservierung von Informationen und Wissen und soll so dem Risiko des Informations- und Wissensverlusts durch Fluktuation ⁷¹ ,

⁶⁸ Natürlich sollte angestrebt sein, dass alle Szenarien funktionieren.

⁶⁹ Vgl. Oestereich u.a. /Objektorientierung/ S. 100

⁷⁰ Vgl. zum folgenden Absatz David /Relevanz/ S. 18-19

⁷¹ Vgl. Yonda /Employees/ S. 1; Oestereich u.a. /Objektorientierung/ S. 90-91; Funke u.a. /Softwareentwicklung/ S. 22; McConnell /Less/ S. 2; Cockburn /Development/ S. 36-37; Locke-

mann u.a. /Systemanalyse/ zitiert nach David /Relevanz/ S. 17; Das Problem wird dadurch noch ver-

schärft, da Fluktuation in der Softwarebranche, dem Saratoga Institute nach, höher ist, als in anderen

Branchen, zitiert nach Müller /Erfolgsfaktoren/ S. 383