Dokumentation Im Quelltext
 
StartSeite | Neues | TestSeite | ForumSeite | Teilnehmer | Kategorien | Index | Hilfe | Einstellungen | Ändern

Im extremen Fall auch: LiterarischesProgrammieren.

Vom Quelltext getrennt erstellte Dokumentation erspart nicht, den Quelltext daraufhin zu überprüfen, ob er auch das tut, was die Dokumentation behauptet. Je näher Informationen zu einer technischen Lösung bei dieser technischen Lösung abgelegt sind, desto schwerer werden sie übersehen, wenn sich die technische Lösung ändert.

Beispiel:

Notwendige Kommentare zu Parametern beschreiben eher den Sinn des Parameters, wenn sie direkt bei diesen Parametern stehen. Noch günstiger ist es, wenn die Parameternamen selber in der Lage sind, den Sinn ohne zusätzlichen Kommentar auszudrücken.

These:

Alle Kommentare, die auch automatisch erzeugt werden könnten, sind als Kommentare sinnlos.

Wenn die Information in der verwendeten Programmiersprache ausgedrückt werden kann, dann soll sie in der Programmiersprache ausgedrückt werden, nicht in einem Kommentar in Prosa.

In diesem Sinne: Der Quelltext ist (wenigstens teilweise - eben soweit möglich) die Dokumentation.

Noch'ne These:

Kommentare, die die Schnittstellen von Klassen, Funktionen, Prozeduren beschreiben, entwickeln sich im Laufe der Lebenszeit von Software häufig zu haarsträubenden Lügen, weil gerade im kommerziellen Programmierumfeld meist die Zeit fehlt, diese Kommentare auf einem aktuellen Stand zu halten.

Interessante Idee zur Bekämpfung dieses Problems:
Die Beschreibung der Schnittstellen wird mit ablauffähigen Beispielen und den von diesen Beispielen zu erwartenden Ausgaben illustriert. Ein separater Automatismus probiert diese Beispiele aus und bildet damit eine Test-Suite aus Einzel-Tests, die sicher stellt, das alle Beispiele auch wie beschrieben funktionieren. Diese Idee wurde z.B. TimPeters? für die SprachePython mit dem Modul doctest ( http://python.sourceforge.net/devel-docs/lib/module-doctest.html) realisiert.


Als Anwenderdokumentation ist der Quelltext nicht geeignet. Trotzdem ist es nicht sinnvoll, Informationen von Hand aus Quelltexten zusammenzutragen, die sich aus diesen auch maschinell gewinnen lassen. Ein gutes Beispiel für die automatische Gewinnung von Dokumentation aus Quelltext ist JavaDoc.

KategorieDokumentation



StartSeite | Neues | TestSeite | ForumSeite | Teilnehmer | Kategorien | Index | Hilfe | Einstellungen | Ändern
Text dieser Seite ändern (zuletzt geändert: 14. August 2001 22:30 (diff))
Suchbegriff: gesucht wird
im Titel
im Text