Code-Style: wie verschönert/verbessert ihr die Lesbarkeit großer Dateien?

[Der schöne Günther]

Zitat von himitsu:

(Code)

Du hast // **** Ab hier geht's los! ..... **** vergessen

[himitsu]

Stimmt, das begin und end muß man noch kommentieren, sonst weiß ja Keiner was das ist.

[nahpets]

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.