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

[p80286]

Zitat:

Zitat von Stevie (Beitrag 1356724)

Übrigens habe ich nicht gesagt, dass man nix dokumentieren/kommentieren sollte, sondern, dass ich deiner Aussage, dass jeglicher Code, sei er noch so kurz, Kommentare aufweisen muss, nicht zustimme - bzw nachfragte, um welche Kommentare es sich dort denn handeln solle. Dass du nun Beispiele nennst, wo Dokumentation und Kommentare notwendig sind, beantwortet diese Frage nicht. :)

Ein Kommentar ist überall da notwendig, wo der Lesende einen zum Verständnis nötigen Background nicht hat.
Wobei

Delphi-Quellcode:

GetlastBookedInvoice

anders kommentiert werden muß als GetLastPosOfIn(Searchedstring,SourceString), falls überhaupt.

Gruß
K-H

[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.

[sakura]

Zitat:

Zitat von Stevie (Beitrag 1356724)

dass ich deiner Aussage, dass jeglicher Code, sei er noch so kurz, Kommentare aufweisen muss, nicht zustimme

Habe ich nicht geschrieben ;) Ich schrieb Unit, und da ist nochmal ein Unterschied.

...:cat:...

[bra]

Besser zu viele Kommentare als gar keine und unverständlicher Code. Ignorieren kann man überflüssige Kommentare immer.

[himitsu]

Ignorieren?

Zuviele unnötige Kommentare machen den Code nur unnötig länger und verbergen die wichtigen Kommentare zwischen ihren unnützen Informationen.

[Sherlock]

Jetzt wirds doch langsam zum Streit zwischen den Unfehlbaren und den Realisten... ;)

Natürlich kann man es übertreiben mit den Kommentaren, und genauso natürlich können sie auch mal schmerzlich fehlen. Das Beispiel mit den Superduper Code mit den Superduper selbsterkärenden Bezeichnern, den man zwei Monate nach der Implementierung plötzlich nicht mehr versteht kam ja mittlerweile von mehreren. Wenn man sich für unfehlbar hält, dann lässt man Kommentare halt weg, ich habe damit kein Problem. Aber wehe dem, der mir seinen Code nicht erklären kann und mit Allgemeinplätzen wie "ist doch selbsterklärend, und Du kannst halt kein Delphi" kommt...

Sherlock

[freimatz]

Zitat:

Zitat von Sherlock (Beitrag 1356538)

Aber zum Thema: Pro Klasse bzw. Klassenbaum eine Unit, und pro Methode nicht mehr als 50 Zeilen, dann wirds schön übersichtlich.

Also bei 2 Millionen Zeilen Code im Projekt gibt das dann recht unübersichtlich viele Dateien. Bei uns darf auch mehr in einer Datei sein, wenn es sachlich zusammengehört und dem unitnamen entspricht. Mit dem bereits erwähnten REGIONS und dem MMX ist das handhabbar.

Zitat:

Zitat von p80286 (Beitrag 1356605)

Übrigens halte ich

Delphi-Quellcode:

{-------- ab hier gehts los -------}

für einen recht sinnvollen Kommentar, wenn z.B. vorher Dutzende von Zeilen mit z.B. Initialisierung und Verifizierung von Werten stehen.

Das halte ich den dümmsten Beitrag in dem ganzen Thread. Das vor dem Kommentar gehört in eine Methoden und das danach auch.

Zitat:

Zitat von p80286 (Beitrag 1356701)

:thumb: :thumb: :thumb:
Aber es gibt Wände, vor die jeder Programmierer einmal selbst laufen muß.

Leider hilft das bei manchen auch nicht :-(

Meine Meinung zu Kommentaren: diese sind wichtig sofern sie das "wozu" und "warum" dokumentieren, nie jedoch wenn es um das "was" und "wie" geht.


Und mal wieder der Hinweis auf: http://clean-code-developer.de/

[Daniel]

Zitat:

Zitat von freimatz (Beitrag 1356933)

Das halte ich den dümmsten Beitrag in dem ganzen Thread.

Und Du dürftest damit wohl den ungeschicktesten Beitrag geleistet haben. :roll:
Wieso sind einige von Euch nicht mehr in der Lage, die Tatsache, dass sie etwas anders sehen, sachlich zu kommunizieren?

[himitsu]

Zitat:

Zitat von freimatz (Beitrag 1356933)

Zitat:

Zitat von p80286 (Beitrag 1356605)

Übrigens halte ich

Delphi-Quellcode:

{-------- ab hier gehts los -------}

für einen recht sinnvollen Kommentar, wenn z.B. vorher Dutzende von Zeilen mit z.B. Initialisierung und Verifizierung von Werten stehen.

Das halte ich den dümmsten Beitrag in dem ganzen Thread. Das vor dem Kommentar gehört in eine Methoden und das danach auch.

Ich bin mir zu 99,99995% sicher, dass das Sarkasmus war. :zwinker: