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.

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.

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.

KategorieDokumentation