Fachbereich 12 der Universität Siegen
Elektrotechnik und Informatik
Prof. Dr.-Ing. Hans Wojtkowiak
Hauptseminar SS 1998
| Betreuer: | Dr.-Ing. Klaus Quibeldey-Cirkel Dipl.-Ing. Georg Odenthal |
| Autor: | Alexander Möller |
Eine Ausarbeitung im Rahmen des Oberseminars "Software-Dokumentation"
Im Hinblick auf die Wiederverwendung oder Nachbearbeitung von Software ist es in den meisten Fällen unumgänglich, sich mit dem Quellcode eines Programms auseinanderzusetzen. In der Regel enthält dieser Quellcode keine oder nur wenig brauchbare Designhinweise. Dies mag einerseits daran liegen, daß die Hauptaufgabe eines Programmierers darin zu sehen ist, Algorithmen und nicht Literatur zu entwerfen und die Erstellung von "guter" Dokumentation sich als recht schwierig gestaltet. Andererseits liegt es auch an der, durch die Industrie vorgegebene, meist kurzen Entwicklungszeit, die dem Softwareentwickler im Anschluß an seine Programmiertätigkeit keine Möglichkeiten mehr geben, die Software entsprechend zu dokumentieren. Die Pflege solcher schlecht verständlicher Software ist gewöhnlich zeitaufwendig und dadurch mit hohen Kosten verbunden. Laut Thomas A. Standish nimmt das Verstehen von Quellcode ca. 50 bis 90 Prozent der Kosten der Instandhaltung einer Software in Anspruch [6].
Um Software mit entsprechend übersichtlicher und schnell verständlicher Dokumentation zu entwickeln und dadurch Zeit und Geld zu sparen, gibt es verschiedene Tools, die den Programmierer bei seiner Arbeit unterstützen. Einige dieser Programmierhilfsmittel basieren auf dem von Donald E. Knuth vorgestellten Literate Programming (1984).
Dieses Dokument erläutert das Grundkonzept dieser Programmiermethode.
"Unsere Hauptaufgabe ist nicht, dem Rechner beizubringen, was er tun soll, sondern Menschen zu erklären, was wir vom Rechner wollen." [2] |
|
|
|
Literate Programming ist eine von Donald E. Knuth im Jahre 1984 vorgestellte Programmiermethode. Sie konzentriert sich im wesentlichen darauf, den Programmierer bei der Erstellung von Softwaredokumentation zu unterstützen.
Gemäß den Überlegung von Knuth benötigt ein erfahrener Programmierer, der eine bestmöglich dokumentierte Software erstellen möchte, zeitgleich zwei Dinge:
Diese zwei Elemente vereinigte Donald E. Knuth in seinem Literate Programming - System, genannt WEB (Dieses ist benannt nach seiner Schwiegermutter Wilda Ernestine Bates.).
Laut Donald E. Knuth besteht eine Programm aus einzelnen Abschnitten, welche durch unterschiedliche Relationen miteinander verknüpft sind. Um ein solches Geflecht verständlich zu dokumentieren, ist es notwendig, die einzelnen Teilstücke und deren Verknüpfungseigenschaften zu erklären. Die Vereinigung einer höheren Programmiersprache (notwendig, um den Lösungsalgorithmus für eine Maschine umzusetzen) und des Textsatzsystems (notwendig, um den Lösungsalgorithmus für einen Menschen verständlich zu machen) stellen eine Art des Programmierens dar, die einerseits die programmtechnische Umsetzung eines Algorithmus erlaubt und andererseits die Dokumentation dieses Algorithmus bietet.
Die mittels Literate Programming entwickelten Programme sind also gleichzeitig lesbar für Mensch und Maschine.
Bei der regulären Softwareentwicklung wird in der Regel als erstes das Programm und im Anschluß die dazu gehörige Dokumentation verfaßt. Da bei der Literate Programming - Methode eine bestmögliche Erläuterung der Software im Vordergrund steht, sollte die Programmentwicklung nicht aus der Sicht eines Programmierers, sondern aus der Sicht eines Autors (Schriftstellers) vorgenommen werden. Die Lösung (der Softwarealgorithmus) wird umgangssprachlich (literarisch) dargelegt und gleichzeitig mit dem zusätzlichen Quellcode verflochten.
Durch diese eher schriftstellerische Vorgehensweise bei der Softwareentwicklung wird automatisch eine Aufgliederung der Handlungsweise in einzelne Kapitel (ähnlich dem Aufbau eines Buches) erreicht. Diese Sichtkapselung fördert einerseits das schnelle Verstehen der Software durch einen späteren Leser und ermöglicht andererseits zum Zeitpunkt der Programmierung eine übersichtlichere Softwareentwicklung, da das Hauptproblem in mehrere Teilprobleme aufgegliedert wird.
David B. Thompson behauptet sogar, daß die mittels Literate Programming erstellte Dokumentation nicht nur übersichtlicher und damit schneller zu verstehen ist, sondern daß sie regelrecht zum Lesen einlädt [1].
Literate Programming vereint den Quellcode und die Dokumentation in einem File. Die regulären Programmkommentare werden entsprechend erweitert und beinhalten die komplette Dokumentation. Mittels Hilfsprogrammen wird nach Bedarf entweder der Sourcecode oder die Dokumentation der Software erstellt.
Bei dem von Donald E. Knuth entwickeltem Literate Programming Tool WEB heißen die Hilfsprogramme Weave und Tangle. Die Abbildung 1 zeigt die prinzipiellen Vorgehensweisen.
Das File "PROG.WEB" stellt das "Literate Program" (siehe Beispiel) dar, welches mittels eines herkömmlichen Editors erstellt werden kann.
Abbildung 1, Anwendung von Weave und Tangle [5]
| Zur Erstellung der Softwaredokumentation ist es notwendig, mit Hilfe des Programms Weave aus dem File "PROG.WEB" ein TEX-File zu erzeugen ("PROG.TEX"). Unter Einsatz des Satzprogramms TEX und des Programms DVIPS kann dieses File dann in ein entsprechendes Postscript-Format ("PROG.PS") umgewandelt und dann ausgedruckt werden. (siehe Abbildung 2) |
Abb. 2, Weave [5] |
|
Abb. 3, Tangle [5] |
Um ein ausführbares Programm zu erstellen, kommt das Softwaretool Tangle zum Einsatz. Als Basis dient wiederum das File "PROG.WEB", aus welchem mit Hilfe des Programms Tangle der entsprechende Programm-Quellcode ausgefiltert und in der Datei "PROG.PAS" abgelegt wird. Dieses kann anschließend mit einem entsprechenden Pascal-Compiler in das ausführbare Programm ("PROG.EXE") transferiert werden. (siehe Abbildung 3) |
Letztendlich dient dem Programmierer als editierbares File ausschließlich das File "PROG.WEB". Sollten also Änderungen am Programmcode oder der Dokumentation notwendig sein, so sollten diese direkt am WEB - File vorgenommen werden, um dann durch die entsprechenden Konvertierungsroutinen das ausführbare Programm oder die Dokumentation zu erhalten.
Ein Beispiel für den Aufbau einer Dokumentation ist in Abbildung 4 zu sehen.
Abbildung 4, Dokumentation aus einem WEB - File [3]
Eine solche Dokumentation besteht aus einzelnen leicht verständlichen Abschnitten, welche im einzelnen folgende Elemente enthalten:
| 1. | Titel des Abschnittes Der Titel gibt in wenigen Worten die Funktion des Abschnittes wieder. Er ist zu vergleichen mit (Kapitel)-Überschriften in Büchern. Das Layout dieses Textes entspricht der Notation des verwendeten Satzprogramms (in der Regel TEX). |
|
| 2. | Beschreibung des Abschnittes
(comment part) Hier ist eine ausführliche Beschreibungen der Funktionsweise des Abschnittes zu finden. Es werden alle relevanten Informationen abgelegt, die für das spätere Verständnis der Software notwendig sind. Diese Informationen können je nach Unterstützung des Satzprogramms Text, Formeln und/oder Grafik enthalten. |
|
| 3. | Definitionen des Abschnittes
(definition part) In diesem Abschnitt werden Makros eingesetzt oder definiert. Ein Makros beinhaltet einen Namen und einen Sourcecodeabschnitt. Der Name gibt die Funktion des Makros wieder und der Sourcodeabschnitt beinhaltet den Algorithmus in der jeweiligen Sprachnotation. |
|
| 4. | Sourcecode des Abschnittes
(source code part) In diesem Abschnitt wird der Programm - Quellcode hinterlegt. In Donald E. Knuths System WEB ist dies Pascal - Quellcode. |
Die einzelnen Elemente eines Abschnittes müssen in dieser Reihenfolge vorliegen. Sie sind jedoch optional und können textlos sein.
Der entsprechende Quellcode, also das WEB - File zu obiger
Dokumentation, ist ein Abbildung 5 dargestellt. Durch vorangehende
Symbole wird den Programmen Weave und Tangle mitgeteilt, wie mit dem
folgenden Text/Code zu verfahren ist. Beispielsweise stehen die Symbole @* für den Beginn
eines neuen Abschnittes. Die genauen Symbolfunktionen können dem WEB - Manual [2] von Donald E. Knuth entnommen werden.
Abbildung 5, Quellcode eines WEB - Files [3]
Auf den ersten Blick scheint Literate Programming dem ausführlichen Kommentieren von Quellcode bei der Softwareentwicklung zu gleichen. Norman Ramsey (Literate Programming FAQ) führt drei wichtige Punkte auf, die den Vorteil von Donald E. Knuths Programmiermethode gegenüber regulärer Programmkommentierung hervorheben:
| 1. | Beliebiger Entwicklungszyklus Durch die, mittels Literate Programming vorgegebene, hierarchische Entwicklung einer Software und die damit verbundene Aufspaltung des globalen Problems in mehrere Teilprobleme, ist eine beliebige Entwicklungsreihenfolge vorgegeben. Dem Programmierer ist es so überlassen, die Rangfolge zu wählen, die dem späteren Leser die Funktionsweise der Software am verständlichsten darlegt. Des weiteren bietet die Kapselung der einzelnen Stücke dem Programmierer eine bessere Möglichkeit, den Code auf Fehler zu überprüfen. Er kann die jeweiligen Programmsequenzen im einzelnen validieren. |
|
| 2. | Automatische Begriffsverknüpfung
(Hypertext) Je nach benutztem Literate Programming Softwaretool können automatisch ein Inhaltsverzeichnis, eine Indexauflistung oder entsprechende Querverweise erstellt werden. Diese Querverweise sind ähnlich dem Hypertext aufgebaut. Je nach Satzsystem besteht die Möglichkeit, durch das Dokument zu "browsen". |
|
| 3. | Dokumentformatierung, inkl.
Diagramme und mathematischer Formeln Durch entsprechende Textformatierung kann die Dokumentation auch visuell informativer gestaltet werden. Dies kann, je nach zu erstellender Software, unter anderem durch das Anzeigen von Diagrammen oder mathematischen Formeln erreicht werden. Beispielsweise können Oberflächendialoge in das Dokument/Programm eingebettet werden. |
Literate Programming wurde von Donald E. Knuth Mitte der 80er Jahre vorgestellt und seither in viele Richtungen weiterentwickelt. Zum damaligen Zeitpunkt wurde als Vereinigung von Satzsystem und Programmiersprache TEX und Pascal gewählt. Heutzutage existieren Programmiertools für viele Sprachen (Pascal, C, C++, Modula, Fortran. Lisp, Ada...). Das Ausgabeformat der Dokumentation ist weitestgehend im TEX-Layout geblieben. Es gibt aber ebenfalls Softwaretools, die die Dokumentation im LATEX-Layout oder im HTML-Layout bereitstellen.
| Des weiteren existieren sogar Unterstützungen für WYSIWYG-Editoren (WhatYouSeeIsWhatYouGet - Editoren) wie WinWord, WordPerfect, AmiPro. Bei Anwendung von WYSIWYG-Editoren entfällt zur Dokumentationsgewinnung in den meisten Fällen die Nachbearbeitung des Literate Programs mittels eines Softwaretools. Der Programmierer erstellt also direkt die fertige Dokumentation (mit den entsprechenden Programmcodesequencen) und es wird mit Hilfe eines Softwaretools ausschließlich der Programmquellcode zwecks Kompilierung ausgefiltert. (siehe Abbildung 6) |  Abbildung 6 |
Näheres zur verfügbaren Software, Sprachunterstützung und den möglichen Ausgabelayouts kann man David B Thompsons Literate Programming FAQ [1] entnehmen. Dort sind auch die Quellen der verfügbaren Literate Programming Tools aufgelistet.
Bei richtiger Anwendung von Literate Programming besitzt man bei Fertigstellung einer Software eine brauchbare Dokumentation, die zum späteren Verständnis des Programmcodes sicherlich helfen wird. Des weiteren ist man bei der Entwicklung von Software gezwungen, Änderungen unmittelbar am WEB-File (dem Literate Program) vorzunehmen. Dies garantiert, daß sowohl die Software als auch die zugehörige Dokumentation immer auf dem gleichen Entwicklungsstand sind.
Man sollte meinen, daß gerade in der heutigen Zeit diese Vorteile Literate Programming dazu verholfen hätten, einen höheren Bekanntheitsgrad zu erreichen. Jedoch muß man ebenfalls sehen, daß die gleichzeitige Erstellung von Dokumentation und Programmcode (wenn auch in einem File, dem Literate Program) mehr Zeit in Anspruch nimmt als die ausschließliche Erstellung eines ausführbaren Programms. Dieses Argument greift um so mehr, da in der Praxis der heutigen Softwareentwicklung zeitlich immer noch vorrangig die Fertigstellung des ausführbaren Progamms steht und erst an zweiter Stelle die dazugehörige Dokumentation folgt.
Ein weiterer negativer Beigeschmack bei der Anwendung von Literate Programming ist die zwar zahlenmäßig große, jedoch qualitativ mäßige Toolunterstützung. Die Entwicklungsumgebungen unter Literate Programming beschränken sich in der Regel auf bessere Text-Editoren, so daß man im Gegensatz zu größeren Entwicklungsumgebungen (beispielsweise von Microsoft oder Borland) ohne Projektverwaltung, Debugger usw. auskommen muß. Der fehlende Komfort bei der Softwareentwicklung mag sicherlich der Hauptgrund für die mangelnde Verbreitung von Literate Programming sein.
Trotz der oben aufgeführten schwerwiegenden Nachteile ist der Grundgedanke von Literate Programming bezüglich der Kombinierung von Programmcode und Dokumentation auch in anderen Bereichen der Softwareentwicklung anzufinden. Ein aktuelles Beispiel hierfür ist Java, welches die Möglichkeit bietet, mittels JavaDoc aus einem Quellcode-File ein Dokumentation in HTML zu erzeugen.
| [1] | David B. Thompson The Literate Programming FAQ Version 1.1.18, 15. August 1997 |
| [2] | Donald E. Knuth WEB User Manual - The WEB System of Structured Documentation |
| [3] | Markus Knasmüller Reverse Literate Programming Linz, Johannes Kepler University |
| [4] | Henrik Turbell Literate Programming Image Proccessing Group, Department of Electrical Engineering, Linköping University März 1997 |
| [5] | Instructor: Marc Abrams CS5014: Research Methods in Computer Science Computer Science Department, Virginia Tech, Blacksburg, VA 24061-0106 |
| [6] | Thomas A. Standish An Essay on Software Reuse; IEEE Transactions on Software Engineering September 1984; Vol. 10, No. 5, 494-497 |
Letzte Änderungen am 12.01.1999
