namespace cpp

C++ lernen, kennen, anwenden

Benutzer-Werkzeuge

Webseiten-Werkzeuge


lernen:document

Unterschiede

Hier werden die Unterschiede zwischen zwei Versionen angezeigt.

Link zu dieser Vergleichsansicht

lernen:document [2014-07-13 16:14] (aktuell)
Zeile 1: Zeile 1:
 +====== Dilemmata der Dokumentation ======
 +
 +>    Das, was am Anfang wie Gift sein kann, doch am Ende wie Nektar ist und einen zur Selbsterkenntnis erweckt, gilt als Glück in der Erscheinungsweise der Tugend.
 +>>​--- ​   Bhagavad-Gita 18.37
 +
 +Es werden einige Methoden der Dokumentation dargestellt und ihre Vor- und Nachteile erläutert. ​
 +Der Text ist nicht als Anleitung zur Dokumentation gedacht. ​
 +Im Gegenteil: Dokumentation ist unmöglich. Dennoch müssen wir es versuchen.
 +
 +Lexikoneintrag:​
 +  * Dokument = Urkunde, Beweisstück [Knaur Konversationslexikon 1936]
 +  * lat. documentum = Belehrung, zu docere = Unterricht geben. Infix men = Mittel, also Mittel der Belehrung [Etymologisches Wörterbuch]
 +
 +===== Ungeliebte Pflicht =====
 +
 +Es scheint paradox: Programmierer heißen Programmierer, ​
 +obwohl sie durchschnittlich höchstens zwei Stunden täglich mit Programmieren verbringen. ​
 +Dies weiß Fred Brooks [Brooks] zu berichten. Der Mann muss es wissen. ​
 +Schließlich war er Projektleiter für das zu seiner Zeit revolutionäre IBM System 360. 
 +Was tun Programmierer in der restlichen Zeit? 
 +Damals war nicht jederzeit Zugang zum Rechner möglich. ​
 +Die Maschine war eine knappe Ressource. Allerdings war sie nicht der Engpass. ​
 +Selbst heute, mit einem PC an jedem Arbeitsplatz,​ hat sich nicht viel geändert. ​
 +"​Produktiver"​ sind die Programmierer nicht geworden. ​
 +Sie schaffen in großen Projekten täglich 10-20 endgültige Quelltextzeilen. ​
 +Sie schlagen ihre Zeit tot, indem sie Dinge tun, die keinen Spaß machen. ​
 +Sie sitzen in Sitzungen, lesen Schriftstücke,​ deren Inhalt sich fortwährend ändert, ​
 +weshalb er neu gelesen werden muss, und verfassen womöglich selber Schriften, ​
 +die sie anderen zusenden (müssen).
 +
 +>  Dokumentation ist das Rizinusöl des Programmierens. Die Manager denken, es sei gut für die Programmierer,​ und die Programmierer hassen es.
 +>   ​Tatsächlich wissen Manager: Es muss gut für sie sein, weil die Programmierer es so hassen.
 +>>​--- ​   Gerald Weinberg
 +
 +Die Welt wäre viel schöner, wenn wir nur die Dinge tun könnten, die Spaß machen. ​
 +Dabei impliziere ich, dass das Programmieren selbst Spaß macht. ​
 +Im Internet findet sind auch die Bemerkung: Dokumentation ist wie Sex. 
 +In gewisser Weise stimmt das auch. 
 +Als Weinberg 1971 die "​Psychologie des Programmierens"​ schrieb, ​
 +stellte er fest, dass es keinen Weg gibt, Programmierer zu zwingen, ​
 +gute Dokumentationen zu produzieren. Zwingen kann man einige Programmierer, ​
 +irgendwelche Dokumentationen zu erzeugen, so wie Kinder gezwungen werden, ​
 +Rizinusöl zu sich nehmen. Es gibt jedoch zuviele Möglichkeiten, ​
 +die Sache zu sabotieren und zu entwerten. Haben die Beteiligten nichts davon, ​
 +wird es auf minimale Weise erledigt. Hat es jedoch gute Effekte, ​
 +gibt es kaum Möglichkeiten,​ gute Dokumentation zu verhindern [Weinberg].
 +
 +===== Quelltext und Dokumentation sind nicht dasselbe =====
 +
 +Form und Inhalt sollten eine ästhetische Einheit bilden. Leider wird dieses Ideal nur selten erreicht. Der "​International Obfuscated C Code Contest"​ kürt die schönsten Programme. Eric Marshalls "choo choo" war Preisträger für Bestes Layout 1986 [IOCCC]:
 +
 +<code c choochoo.c>​
 +extern int
 +errno
 +;char
 +grrr
 +                             ;​main( ​                          r,
 +  argv, argc )            int    argc                           ,
 +   ​r ​       ;           char *argv[];​{int ​                    P( );
 +#define x  int i,       ​j,​cc[4];​printf(" ​     choo choo\n" ​    ) ;
 +x  ;if    (P(  !        i              )        |  cc[  !      j ]
 +&  P(j    )>​2 ​ ?        j              :        i  ){*  argv[i++ +!-i]
 +;              for    (i=              0;;    i++                   );
 +_exit(argv[argc- 2    / cc[1*argc]|-1<<​4 ]    ) ;​printf("​%d",​P(""​));​}}
 +  P  (    a  )   char a   ; ​ {    a  ;   ​while( ​   a  >      " ​ B   "​
 +  /* -    by E            ricM    arsh             ​all- ​     */);    }
 +</​code>​
 +Was produziert es?
 +
 +Ziel des IOCCC-Wettbewerbs ist nicht, gute Dokumentation zu schulen. ​
 +Er leuchtet vielmehr dunkle Ecken aus:
 +
 +  *  Schreibe den obskursten, verhunztesten C-Quelltext.
 +  *  Demonstriere die Wichtigkeit eines Programmierstils (ironisch)
 +  *  Teste Compiler mit unüblichem Quelltext
 +  *  Verdeutliche Eigenheiten von C-Programmen
 +  *  Forum für "​schlechte"​ Quellen
 +
 +Brian Westleys "​pi"​ gewann 1988 den Preis für Bestes Layout. ​
 +Als Erläuterung gab er an, dass dieses Programm die Kreiszahl pi berechnet; ​
 +für genauere Werte brauche man nur ein größeres Programm schreiben. ​
 +Das Programm verschleiert (obfuscate = verhüllen) kaum, 
 +dass die Berechnung mittels der Kreisflächenformel $A=\pi*d^2/​4$ erfolgt. ​
 +Es erfordert jedoch etwas Mühe, bis man dies erkennt. Es funktioniert nur, 
 +falls der Präprozessor aus zwei aufeinander folgenden Minuszeichen ein Doppelminus-Token erzeugt:
 +
 +<code c pi.c>
 +#define _ -F<​00||--F-OO--;​
 +int F=00,​OO=00;​main(){F_OO();​printf("​%1.3f\n",​4.*-F/​OO/​OO);​}F_OO()
 +{
 +            _-_-_-_
 +       ​_-_-_-_-_-_-_-_-_
 +    _-_-_-_-_-_-_-_-_-_-_-_
 +  _-_-_-_-_-_-_-_-_-_-_-_-_-_
 + ​_-_-_-_-_-_-_-_-_-_-_-_-_-_-_
 + ​_-_-_-_-_-_-_-_-_-_-_-_-_-_-_
 +_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_
 +_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_
 +_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_
 +_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_
 + ​_-_-_-_-_-_-_-_-_-_-_-_-_-_-_
 + ​_-_-_-_-_-_-_-_-_-_-_-_-_-_-_
 +  _-_-_-_-_-_-_-_-_-_-_-_-_-_
 +    _-_-_-_-_-_-_-_-_-_-_-_
 +        _-_-_-_-_-_-_-_
 +            _-_-_-_
 +}
 +</​code>​
 +Soweit zum Spaß.
 +
 +===== Quelltext ist nicht alles =====
 +
 +Nur selten reicht der Quelltext aus, um seine Wirkung zu verstehen. ​
 +Aus diesem Grund wird er mit Kommentaren versehen. ​
 +Der richtige Einsatz von Kommentaren erfordert Erfahrung:
 +
 +<code c>
 +  for(i=0; i<​anzahl;​ i++) // fuer alle Feldelemente:​
 +    feld[i] = 0;              // auf Null setzen
 +</​code>​
 +
 +Hier wurde einem C-verständigen Leser keine zusätzliche Information gegeben. ​
 +Der Kommentar soll nicht wiederholen,​ was ohnehin schon da steht. ​
 +Der Quelltext ist selbsterklärend. Da er von Programmierern gelesen wird, 
 +sollte jener auch verstehen, was getan wird. Im Quelltext steht jedoch nicht, ​
 +warum das Feld initialisiert wird. 
 +Dies muss eine Dokumentation oder ein Kommentar leisten. ​
 +Der Programmierer braucht die Übersicht, in welchem Rahmen das Feld verwendet wird, 
 +unter welcher Einsatzbedingung die Feldwerte zu nullen sind. 
 +Das kann Quelltext nicht leisten. ​
 +Auch technische Dokumentierwerkzeuge werden das nicht erkennen können. ​
 +Könnten sie es, wäre vermutlich auch der Beruf des Programmierer überflüssig. ​
 +Solange künstliche Intelligenz nicht als Ersatz für natürliche Dummheit verfügbar ist 
 +(ich hoffe, das bleibt noch eine Weile so), solange nimmt uns jedoch keiner diese Mühe ab.
 +
 +Dokumentiere das Warum; das Wie steht im Quelltext. ​
 +Eine Ursache, dass Dokumentieren ungeliebt ist, steckt darin. ​
 +Wir müssen nachdenken und Rechenschaft ablegen, nicht, was wir tun, 
 +sondern vor allem, warum. Wir müssen Beweggründe offenlegen, ​
 +die zur Entscheidung für ein Vorgehen führten. Dokumentieren ist aufwendig. ​
 +Dies beim Implementieren zu erledigen, ​
 +widerspricht dem Streben nach Zerlegung in Teilaufgaben. ​
 +Warum soll ich dokumentieren,​ wenn noch gar nicht klar ist, 
 +ob etwas überhaupt funktioniert?​ Warum dokumentieren,​ wenn ich der einzige bin, 
 +der den Code zu Gesicht bekommt? ​
 +Andere interessieren sich nur für die Schnittstellen. ​
 +Dafür gibt es Dokumentations-Generatoren...
 +
 +===== Wo steckt die Dokumentation im System? =====
 +
 +Doku-Generatoren nutzen in den Quelltext eingebaute Kommentare. ​
 +Ausführbare Dokumente gehen den umgekehrten Weg. 
 +Literate Programming und Case Tools setzen eine eigene Ebene darüber.
 +
 +<​code>​
 ++--------\ ​ Dok-Generator ​  ​+---------------\
 +| Quelle | --------------> ​ | Dokumentation |
 ++--------+ ​                 +---------------+
 +
 ++--------\ ​  ​ausführbare ​   +---------------\
 +| Quelle | <​-------------- ​ | Dokumentation |
 ++--------+ ​  ​Dokumente ​     +---------------+
 +
 +               ​+--------------------------\
 +               | WEB-Dokument / Case Tool |
 +               ​+--------------------------+ ​
 +         ​tangle ​ |                      |  weave 
 +                 ​v ​                     v  ​
 +         ​+--------\ ​                ​+---------------\
 +         | Quelle |                 | Dokumentation |
 +         ​+--------+ ​                ​+---------------+
 +</​code>​
 +Alle diese Ansätze verfolgen ein gemeinsames Ziel: One Source. ​
 +Ansonsten bleibt nur die Parallel-Entwicklung mit der Gefahr: ​
 +Stimmen Quelltext und Dokumentation nicht überein, sind vermutlich beide falsch.
 +
 +===== Dokumentation aus dem Quelltext =====
 +
 +Hunt und Thomas [Hunt] geben folgenden Rat für den pragmatischen Programmierer: ​
 +Wiederhole dich nicht! Der Quelltext ist das, worauf es ankommt. ​
 +Wie etwas getan wird, steht im Quelltext. ​
 +Variablen- und Typnamen sollten sorgfältig und bedeutungsvoll gewählt werden. ​
 +Irreführende Namen sind noch schlimmer als bedeutungslose:​ sie führen zu Chaos. ​
 +Bedenke: Der Quelltext wird hunderte Male gelesen, aber (hoffentlich) nur wenige Male geschrieben. ​
 +Kommentare sollten das Geschriebene nicht wiederholen,​ sondern erläutern, ​
 +warum dies so getan wird. Handwerkliche Kompromisse können erläutert, ​
 +Stolperstellen markiert werden, ​
 +Dinge, für die sonst nirgends Platz in der Dokumentation vorgesehen ist. 
 +Gut dokumentierter Quelltext enthält
 +
 +  *  einen einleitenden Kommentarkopf für die Datei, der zumindest den Zweck des Quelltextes beschreibt, der Name des Autors für Rückfragen;​ weitere Angaben wie Reifegrad, Revisionen, bekannte Fehler usw. können enthalten sein,
 +  *  eine Erläuterung für jede Klasse und
 +  *  eine Erläuterung für jede (nicht triviale) Methode oder Funktion.
 +
 +Wie diese Kommentare auszusehen haben, kann in Codierungsstandards festgelegt sein. 
 +Es wird auch beeinflusst von der Art der Systeme, mit denen gearbeitet wird. 
 +Editoren sind empfänglich für bestimmte Zeichenfolgen. ​
 +Falten-Editoren können Teile des Quelltextes aus- oder einblenden. ​
 +Versionskontrollsysteme können Kommentare in den Quelltext einbauen etc. 
 +Dokumentationsgeneratoren können aus solchen Kommentaren Referenz-Dokumente herausziehen. ​
 +Zum Java-Entwicklungssystem gehört Javadoc. ​
 +Für C++ gibt es neuerdings ähnliche Systeme (Doxygen). ​
 +Ein Java-Dokumentationskommentar-Beispiel:​
 +
 +<code java>
 +/**
 +  * Generate the inverse of a quadratic matrix.
 +  *
 +  * @param ​ matrix The matrix to invert.
 +  * @return the inverse matrix, if matrix is not singular.
 +  * @exception Singular When determinant(matrix) is zero.
 +  *
 +  * @see QuadraticMatrix
 +  * @see Singular
 +  * @see LinearAlgebra
 +  * @author R. Richter
 +  * @version 0.95, 2002-10-22
 +  */
 +public QuadraticMatrix inverse(QuadraticMatrix matrix) throws Singular;
 +</​code>​
 +
 +Der Vorteil dieser Technik liegt darin, dass stets eine aktuelle, ​
 +vollständige Referenz der Klassenschnittstellen generiert und 
 +auch online verbreitet werden kann. 
 +Diese HTML-Referenzdokumente können Querverweise auf andere Module enthalten ​
 +und so ein "Netz des Wissens"​ über das System erzeugen. ​
 +Ein Vorteil des Verfahrens ist, dass die Information über eine Funktion, ​
 +Methode oder Klasse an einer Stelle lokalisiert ist 
 +(Prinzip: one source --- wiederhole dich nicht). ​
 +Das mindert die Gefahr, dass Quelltext und Dokumentation sich auseinander entwickeln.
 +
 +Der Pferdefuß liegt in dem Wort kann. Dokumentation ist nicht kostenlos. ​
 +Man muss einen solchen Stil aktiv pflegen. ​
 +Unsere Werkzeuge sollten das erleichtern. ​
 +Ordentliche Editoren für Programmierer sind in der Lage, 
 +für diesen Zweck vorgefertigte Kommentar-Bausteine mit wenigen Tastendrücken in den Quelltext einzufügen.
 +
 +===== Quelltext aus dem Dokument =====
 +
 +Jedes Modul, jede Klasse, jede Funktion, ​
 +jede globale Variable für sich getrennt zu erläutern, ist eine Methode. ​
 +Sie hat aber den Nachteil, ​
 +dass diese Kommentare nur ein loses Netz von Referenzdokumenten ergeben. ​
 +Netze bergen auch die Gefahr, sich darin zu verheddern. ​
 +Ohne Leitdokumente kann sehr schnell die Orientierung verloren gehen. ​
 +Es gibt eine entgegengesetzte Methode, die versucht, ​
 +den Quelltext logisch aufeinander folgend in einem unterrichtenden Stil 
 +(im Wortsinn als Dokument) zu entwickeln. ​
 +Diese Idee wurde von Donald E. Knuth für die Entwicklung des Textsatzsystems TEX benutzt ​
 +und als "​Literate Programming"​ bekannt gemacht [TeX]. ​
 +Aus einem WEB-Dokument kann sowohl den Quellcode zusammengesetzt (tangle = verknoten) ​
 +als auch eine druckfertige Dokumentation erstellt werden (weave = verweben). ​
 +Die beiden Prozesse Tangle und Weave erzeugen unterschiedliche Sichten (Projektionen) ​
 +eines einheitlichen Dokumentes. Obwohl die Idee verlockend ist, 
 +hat sie sich nicht auf breiter Front durchgesetzt. ​
 +Es gibt nur eine relativ kleine Gemeinde von Nutzern und einen Haufen Propaganda. ​
 +Offensichtlich ist der Aufwand, das WEB-System zu verstehen, sehr hoch. 
 +Der Schreiber muss drei Sprachen gleichzeitig beherrschen und auseinander halten: ​
 +die Programmiersprache,​ die Sprache des Textsatzsystems und die WEB-Syntax. ​
 +Ausführbare Dokumente lassen sich auch ohne so großen Aufwand produzieren. ​
 +ASCII-Klartext (HTML, LaTeX, troff oder RTF) mit einigen Textmarken reicht vollkommen aus:
 +
 +<code cpp>
 +//: hallo.cpp : Hallo-Programm - R.Richter 2002-10-22 ​  <- Anfang ​
 +#include <​iostream> ​
 +using namespace std;
 +
 +int main()
 +{
 +  cout << "​Hallo,​ Welt" << endl;
 +  return 0;
 +}
 +//~   <- Ende des Quelltextes
 +</​code>​
 +
 +Einfache Werkzeuge (Perl oder [[anwenden:​onesource:​extract|eigene kleine Programme]]) ​
 +sind in der Lage, 
 +so markierte Quellen für die Übersetzung aus dem Dokument herauszuziehen. ​
 +Gerade für Lehrbücher ist diese Technik hervorragend geeignet, um sicherzustellen, ​
 +dass die Programmbeispiele tatsächlich lauffähigen Quelltext ergeben [Eckel]. ​
 +Es gibt einen Haufen schlecht übersetzter Bücher, ​
 +bei denen die automatische Rechtschreibkorrektur die Quelltexte entstellt:
 +
 +  If(! anwender_besitzt_hund)
 +  Cout << "Sie sollten sich einen Hund anschaffen"​ << endl;
 +
 +...der den Übersetzer von [Jamsa] beißt. ​
 +So etwas Ärgerliches kann man nicht als Lehrbuch bezeichnen. ​
 +Textbearbeitungsprogramme sind nicht nur "zu intelligent"​ für manchen Zweck. ​
 +Sie speichern die Dokumente auch noch in einem herstellereigenen (proprietären), ​
 +meist nicht oder nicht ausreichend dokumentierten (da haben wir'​s!) Format, ​
 +das sich mindestens aller zwei Jahre so ändert, ​
 +dass vorhergehende Textversionen nicht mehr bearbeitet werden können. ​
 +Um meine 15 Jahre alte Dissertation heute noch mal ausdrucken, ​
 +müsste ich die alte Textverarbeitung nochmal aufspielen, ​
 +evtl. das Betriebssystem "​downgraden"​ und hoffentlich den passenden Druckertreiber finden, ​
 +der alle mühevoll kontrollierten Seitenumbrüche durcheinanderwirft. Nein, danke. ​
 +Es ginge vermutlich schneller, sie nochmal in LaTeX zu setzen... ​
 +LaTeX ist seit 20 Jahren stabil.
 +
 +===== Case Tools setzen noch eins drauf =====
 +
 +Case Tools beantworten die Frage nach der Herkunft von Quelltext und Dokumentation ganz anders. ​
 +Dem Programmierer (darf man den hier noch so nennen?) oder Entwickler ​
 +wird eine herstellerspezifische Oberfläche angeboten, ​
 +auf der unterschiedliche Sichten der entstehenden Software-Lösung zu bearbeiten sind. 
 +Dahinter steckt meist ein kompliziertes System aus proprietären ​
 +(und meist nicht dokumentierten) Binärdateien,​ aus denen bei Bedarf, ​
 +d.h. auf Knopfdruck, Dokumentationen zusammengestellt oder auch Quellcode generiert wird.
 +
 +Als die Idee der Case Tools aufkam, schien die Verheißung, ​
 +nie wieder unverständlichen Quelltext tippen zu müssen, die Produktivität zu erhöhen. ​
 +Natürlich erst, nachdem man sich in das neue System eingefuchst hat. 
 +Fred Brooks hat uns gewarnt: Es gibt keine "​Silberkugel", ​
 +die uns der Mühen enthebt, keinen Stein der Weisen [Brooks2].
 +
 +Das Problem der Case Tools ist dasselbe wie das der WYSIWYG-Texteditoren: ​
 +"What You See Is All You Get." [Kernighan] ​
 +Man sieht immer nur eine Sicht, da der Bildschirm immer zu klein ist. 
 +Auch kann man innerhalb des Systems nicht darlegen, was und vor allem, ​
 +warum man etwas getan hat. Dies muss man sich wieder außerhalb notieren. ​
 +Damit stehen wir vor demselben Problem, nur auf höherem Niveau. ​
 +Nebenbei noch eine Preisfrage: Mit welchem System werden Case Tools entworfen?
 +
 +Man erhält innerhalb des Systems keine Übersicht, ob der Entwurf / 
 +die Umsetzung abgeschlossen ist. Den generierten Quelltext durchzuarbeiten, ​
 +ist meist grauenhaft, da dieser von einer Maschine für eine Maschine erzeugt wurde, ​
 +ohne Rücksicht auf eventuelle menschliche Leser. ​
 +Wird dort doch ein Fehler gefunden, bleibt die Schwierigkeit, ​
 +die entsprechende Stelle im Case Tool zu lokalisieren.
 +
 +Case Tools müssen, um erfolgreich zu sein, häufig gestellte Probleme nachbilden. ​
 +Die Entwickler von Case Tools stehen im Zweispalt, ​
 +entweder eine Sache richtig oder viele nur halb zu machen. ​
 +Bei der Entwicklung bleibt meist keine Zeit, für seltene Probleme Lösungen vorzusehen. ​
 +Case Tools sind begrenzte, geschlossene Systeme. ​
 +Sie können nur mit wenigen Sprachen, Compilern, Betriebssystemen zusammenarbeiten. ​
 +Es besteht meist keine Möglichkeit,​ innerhalb des Systems Erweiterungen vorzunehmen.
 +
 +Proprietäre Binärformate werden zum Hindernis beim Versions- und System-Wechsel. ​
 +Sie verstoßen gegen die im vorigen Abschnitt geschilderte schmerzvolle Erfahrung: ​
 +Nutze nur menschlich lesbare ASCII-Formate für wichtige Daten.
 +
 +===== Das System zerbricht =====
 +
 +Das Ideal, alles im selben System zu dokumentieren,​ ist selten erreichbar. ​
 +Eine Idee ist schnell skizziert. Dafür reichen manchmal wenige Bleistiftstriche auf Papier. ​
 +Muss die Idee in elektronischer Form gespeichert werden, steht die Frage: ​
 +textliche Beschreibung oder Bild? Ein Text ist als ASCII-Text speicherbar, ​
 +kann aber missverständlich formuliert sein. 
 +Ein Bild kann komplexere Zusammenhänge besser veranschaulichen. ​
 +Ein Bild ist soviel wert wie tausend Worte. ​
 +Manchmal kostet ein Bild auch mehr als 2 KByte (1 Computerwort = 2 Byte). ​
 +Statt die Bleistiftskizze in die Tat umzusetzen, verbringen wir viel Zeit damit, ​
 +das Bild zu bearbeiten, denn hat man das Bild dann schon in elektronischer Form, 
 +möchte man es gern auch perfekt, dokumentationsbereit,​ haben. ​
 +Bilder, egal, ob in Pixelform (eingescannte Skizze) ​
 +oder im Vektorformat sind aber das Paradebeispiel für inkompatible Dateitypen. ​
 +Gerade in diesem Bereich fällt die Normierung ausgesprochen schwer.
 +
 +===== Medien-Brüche =====
 +
 +Doch gibt es einen viel gewichtigeren Grund, ​
 +warum geschlossene Dokumentationssysteme nicht funktionieren. ​
 +Dokumentation beginnt schon lange vor der Implementierung, ​
 +vor dem Einsatz von Case Tools. ​
 +Das Dokumentationsproblem betrifft alle Phasen des Entwicklungsprozesses:​
 +
 +| Analyse | Dokumentation | Kommunikation mit Kunden, Pflichtenheft |
 +| Entwurf | " | Analyse-Ergebnisse,​ Entwurfsdokumente |
 +| Codierung | " | Quelltexte, Bibliotheksreferenzen,​ Übersetzungsverfahren |
 +| Test     | " | Testfälle, Testverfahren,​ Testberichte |
 +| Einsatz | " | Installationsverfahren,​ Nutzerhandbücher,​ Online-Hilfen |
 +| Wartung | Dokumentation | Fehlerbehebungsprotokolle,​ Hotline-Anweisungen etc. |
 +
 +Und Dokumentation richtet sich nicht an eine homogene Gruppe von Adressaten. ​
 +Manager, Analytiker, Projektleiter,​ Entwickler, Teammitglieder, ​
 +Service-und Wartungspersonal,​ Kunden, Anwender und Bediener ​
 +(die letzten drei Gruppen sind nur im Heimbereich identisch!). ​
 +Unter den Bedienern wiederum gibt es unterschiedliche Schulungsgrade. ​
 +Manchem ist schon mit einer Kurzeinführung ("​Getting Started with XYZ") geholfen. ​
 +Es gibt Bedienhandbücher,​ die Handlungsabläufe dokumentieren, ​
 +Referenzhandbücher,​ die alle Begriffe und Verfahren alphabetisch sortiert und unzweideutig, ​
 +manchmal aber schwer verständlich aufführen, und solche, ​
 +die stumpfsinnig Menüpunkt für Menüpunkt aufzählen ​
 +(meist entstanden während eines dreiwöchigen Bade- und Arbeitsurlaubs ​
 +eines "​Erfolgsautors"​ mit Laptop und einer Betatestversion der Software).
 +
 +Nicht jeder Programmierer ist gleichzeitig ein begnadeter technischer Schreiber. ​
 +(Ich will nicht gleich Schriftsteller sagen.) ​
 +Es wäre ideal, aber die Welt ist nicht so. 
 +Nicht jeder Dokumentierer muss auch gleichzeitig die Software ​
 +bis in den letzen Winkel auswendig kennen. ​
 +Dies schaffen schon die Anwendungsprogrammierer nicht. ​
 +Auch da herrscht Arbeitsteilung. Ohne diese wären große Systeme nicht zu bauen. ​
 +Alleskönner sind so teuer, dass keine Firma sich leisten kann, 
 +nur solche zu beschäftigen,​ abgesehen davon, dass solche selten sind. 
 +Dann jedoch müssen Verfahren gefunden werden, ​
 +wie die Information von den Programmierern zu den Dokumentatoren kommt. ​
 +Professionelle Dokumentation muss nicht vom Programmierer allein getan werden, ​
 +aber sie sollte mit Unterstützung des Programmierers erfolgen. ​
 +Hier haben wir wieder psychologische und manchmal betriebsorganisatorische Barrieren: ​
 +Wer bezahlt dafür? Zeit ist die kostbarste Ressource. ​
 +Dokumentation als den letzten, ​
 +unter Zeitdruck vernachlässigbaren Schritt des Entwicklungsprozesses anzusehen, ​
 +ist ein beliebter Fehler, der im traditionellen,​ veralteten Wasserfallmodell wurzelt: ​
 +
 +  Analyse > Entwurf > Umsetzung > Test > Dokumentation > Einsatz. ​
 +
 +Es gibt inzwischen bessere Vorgehensmodelle. ​
 +Dokumentation muss während des Prozesses erfolgen. ​
 +Nach einem halben Jahr kann sich niemand mehr erinnern. ​
 +Ein ständiger Abgleich mit den Entwurfszielen ist notwendig.
 +
 +Dokumentation und Programm dürfen sich nicht auseinander entwickeln. ​
 +Tun sie es, und sehr oft ist das der Fall, 
 +kann dies das Scheitern des Projektes nach sich ziehen.
 +
 +Gedruckte Dokumente stellen immer einen Schnappschuss des Systems dar. 
 +Das System entwickelt sich danach weiter. Sehr oft sind dann Dokumente veraltet. ​
 +Mit Hypertextsystemen und weltweiten Netzen können Online-Dokumente zeitnah abgefragt werden. ​
 +Hier können Automatisierungstechniken mit Erfolg eingesetzt werden. ​
 +Allerdings kommt diese Technik auch nicht kostenlos daher. ​
 +Die Frage ist immer: Wer bezahlt dafür? Wie hoch ist der Preis? ​
 +Was ist die Alternative?​ Gibt es ein "​Entrinnen"?​
 +
 +===== Technische Lösungen für soziale Probleme? =====
 +
 +> Der Mensch wird auf die Dauer zu dem, mit dem sich sein Geist beschäftigt. Das gilt selbstverständlich auch für Leute, deren Aufgabe darin besteht, tagtäglich über Dinge nachzusinnen,​ die mit unseren elektronischen Rechenanlagen zu tun haben.
 +>>--- Joseph Weizenbaum
 +
 +Oder um einen alten Witz zu zitieren: ​
 +Was macht der Programmierer,​ wenn er Ehe-Probleme hat? Er schreibt ein Programm dafür.
 +
 +Programmierer und Techniker allgemein neigen dazu, 
 +für Problemstellungen technische Lösungen zu suchen, auch dann, 
 +wenn es allgemein (zwischen-) menschliche,​ soziale Probleme sind. 
 +Weil demokratische Wahlergebnisse knapp oder umstritten sein können, ​
 +sollen wir sie einer Wahlmaschine übertragen?​ Was hindert uns daran, ​
 +deren Ergebnis in Frage zu stellen? Weil Terroristen Flugzeuge entführen, ​
 +sollen die Flugzeuge ferngesteuert werden. ​
 +Flugleitzentralen zu besetzen oder Funkstrecken zu stören ist genauso möglich. ​
 +Weizenbaum kritisiert zurecht, daß wir technikzentriert denken. ​
 +Er sagt sogar: Soziale Probleme sind generell nicht lösbar, ​
 +auch nicht mit technischen Mitteln, denn es sind Probleme, ​
 +die aus den Eigenheiten der Menschen und ihren Beziehungen untereinander entstehen.
 +
 +Dokumentation dient der Kommunikation und ist damit ein soziales und psychologisches Problem. ​
 +Das Dokumentationsproblem ist vermutlich nie lösbar. ​
 +Dennoch müssen wir immer wieder Wege finden, ​
 +wichtige Informationen für die Nutzung unserer Systeme verfügbar zu machen. ​
 +Technische Lösungen können uns dabei allenfalls unterstützen. Nutzen wir sie.
 +
 +==== Quellen ====
 +
 +  * [Brooks] Frederick P. Brooks jr.: The Mythical Man-Month. Addison-Wesley,​ Reading, Mass. (1975) Silver Anniversary Edn. (1995). ISBN 0-201-83595-9 ​
 +  * [Weinberg] Weinberg: The Psychology of Programming. Dorset House, New York (1971). Silver Anniversary Edn. (1998). ISBN 0-932633-42-0 ​
 +  * [IOCCC] The International Obfuscated C Code Contest. http://​www.ioccc.org ​
 +  * [Hunt] Andrew Hunt, David Thomas: The Pragmatic Programmer. AddisonWesley,​ Reading, Mass. (1999). ISBN 0-201-61622-X ​
 +  * [TeX] Donald E. Knuth: The TeX Book. Addison-Wesley,​ Reading, Mass. (1986). ISBN 0-201-13447-0 ​
 +  * [Jamsa] Kris Jamsa: C++ Von Null auf Hundert. Elektor, Aachen (2000), S. 83. 
 +  * [Brooks2] Frederick P. Brooks jr.: No Silver Bullet. IEEE Computer Vol 20, 4(1987). Nachdruck in: [Brooks]. ​
 +
 +Weiterführende Literatur:
 +
 +  * [Thaller] Georg Erwin Thaller: Software-Dokumente. Heise, Hannover (1995). ISBN-88229-057-9
 +
  
lernen/document.txt · Zuletzt geändert: 2014-07-13 16:14 (Externe Bearbeitung)