Am Anfang einer meiner Units steht dieser Kommentar:
Delphi-Quellcode:
{
Unit Name: SBAutoRegistry
Purpose: Speichert Konfigurationsdaten automatisch in der Registry und liest
diese beim Programmstart wieder aus. Bietet beim Start das
Ereignis OnRead und beim Beenden das Ereignis OnWrite an.
Führt eine eigene Fehlerbehandlung im Programm ein, die ggfls. mit
Hilfe der JCL genauere Fehlerinformationen ermittelt. Hierzu muss
das Programm mit ausfühlicher MAP-Datei erstellt werden.
Beim Auftreten von Fehlern wird das Ereignis OnAppException
ausgelöst. Hier kann im Programm entsprechend reagiert werden.
Konfigurationsabhängig können hier nur die einfachen Fehlermeldung
(Exception.Message) ausgegeben werden oder genauere, von der JCL
ermittelte Informationen, wie Fehleradresse, fehlerverursachender
Ort im Quelltext ...
Programmfehler können automatisch in einer LOG-Datei protokolliert
werden. Die Protokollierung ist ein- und ausschaltbar.
Der Aufruf einer kontextsensitiven Hilfe wird hier zentralisiert,
ebenso die Anzeige von Hints.
Für alle Formulare des Programmes werden die Positionen, Höhe und
Breite in der Registry gespeichert, um die Positionen bei einem
Neustart des Programmes zu restaurieren.
}
Wenn man den nachfolgenden Quelltext liest (ca. 1600 Zeilen), kommt man an die gleiche Information. Der Quelltext ist so gehalten, dass er lesbar ist, also sprechende Bezeichner für alles, was da so genutzt wird.
Beim Lesen des Quelltextes erhält man also die gleiche Information. Strenggenommen ist der Kommentar also Redundanz und könnte ohne Informationsverlust entfernt werden.
Trotzdem halte ich so eine Beschreibung am Anfang für sinnvoll. Sie ist deutlich schneller und leichter verstehbar, als die entsprechende Implementierung.
Und sollte mal ein Laie aus der QS, beim Kunden oder wo auch immer genötigt sein, in den Quelltext zu schauen, so kann er am Anfang der
Unit kurz und knapp die benötigte Info zum Sinn und Zweck der
Unit erhalten.
Ein neuer Entwickler im Team kann so auch kurz mal reinschauen und bereits anhand des Kommentares entscheiden, ob die
Unit für die Aufgabe, die er da gerade erledigen soll, geeignet ist / sein könnte oder eben auch nicht.
Und wenn ich mal in die Quellen der JVCL schaue, so finde ich es durchaus praktisch, am Anfang eine Beschreibung zu finden, statt erst den gesamten Quelltext lesen zu müssen.
Bei komplexen Algorithmen ist eine Beschreibung für mich ein muss. Im Quelltext bekomme ich ggfls. nämlich nur die falsche Implementierung zu lesen, ohne eine Information darüber, wie es denn eigentlich sein soll.
Da helfen mir die beste Lesbarkeit und die tollsten und aussagekräftigsten Bezeichner nichts, wenn sie etwas anderes darstellen, als bei der zu lösenden Aufgabe eigentlich gemeint war, weil nämlich die bei der Implementierung falsch verstanden wurde.
Zuweilen mal bei der Fehlersuche eine vollständige und korrekte Beschreibung zum Quelltext zu haben, ist nicht so ganz ohne.
Trivialitäten werden selbstverständlich nicht kommentiert.