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

[Stevie]

Zitat von sakura:

Quellcode komplett ohne jegliche Kommentare ist aus meiner Sicht ein generelles No-Go, egal wie klein die Unit ist.

Und was genau soll man bei selbsterklärendem Code kommentieren?

Siehe auch: https://blog.codinghorror.com/coding-without-comments/

[sakura]

Zitat von Stevie:

Und was genau soll man bei selbsterklärendem Code kommentieren?

Meiner Erfahrung nach gibt es den nicht
Aus der genannten Seite:

Zitat:

Perhaps that's the dirty little secret of code comments: to write good comments you have to be a good writer.

Was meine ich mit "gibt es nicht" - je nach Level der anderen mitarbeitenden (zukünftigen) Entwickler - sowohl generell, als auch Sprach- bzw. Projekt-spezifisch, gibt es in komplexen Systemen nichts, wo nicht ein wenig Dokumentation angebracht ist. Sei es eine Beschreibung des Typen, der Methodenparameter, auftretender Exceptions, oder - innerhalb der Methode - die Logik. Letzteres ist das, was oft am wenigsten nötig ist, aber Schnittstellen und Methoden sollten meiner Erfahrung nach immer eine Beschreibung mit sich bringen.

......

[Stevie]

Zitat von sakura:

Was meine ich mit "gibt es nicht" - je nach Level der anderen mitarbeitenden (zukünftigen) Entwickler - sowohl generell, als auch Sprach- bzw. Projekt-spezifisch, gibt es in komplexen Systemen nichts, wo nicht ein wenig Dokumentation angebracht ist.

Solche Dokumentation zum "Großen Ganzen" findet sich aber eher nicht innerhalb einer bestimmten Sourcecode Datei.

Zitat von sakura:

Sei es eine Beschreibung des Typen, der Methodenparameter, auftretender Exceptions, oder - innerhalb der Methode - die Logik. Letzteres ist das, was oft am wenigsten nötig ist, aber Schnittstellen und Methoden sollten meiner Erfahrung nach immer eine Beschreibung mit sich bringen.

Kann man sich das meiste von sparen, indem man die Dinge entsprechend benennt - siehe Beispiel von Jeff im Artikel.
Es reicht allerdings nicht nur eine gute Benamung sondern auch das Einhalten, bestimmter Prinzipien, z.B. des Single Level of Abstraction - womit man aus dokumentier/kommentierwürdigen if/while/for- Code Klumpen einfach verständliche und selbsterklärende Subroutinen formen kann.

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

[himitsu]

Zitat von Stevie:

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

Delphi-Quellcode:

///   <summary>
///     Das ist die Funktion Sum aus der Datei Unit1.
///   </summary>
function Sum(A, B: Integer): Integer;
var
  Temp: Integer;  // eine lokale Variable und wehe jemand meckert, aber ich hatte sonst nichts zum Kommentieren
begin
  Temp := A + B;  // beide Zahlen addieren
  Result := Temp;  // weist das Ergebnis zu
end;

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

[p80286]

Zitat von Stevie:

Ü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 GetlastBookedInvoice anders kommentiert werden muß als GetLastPosOfIn(Searchedstring,SourceString), falls überhaupt.

Gruß
K-H

[sakura]

Zitat von Stevie:

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.

......

[bra]

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