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

[p80286]

Zitat:

Zitat von ConnorMcLeod (Beitrag 1356659)

Es hat Gründe, warum man es nicht so macht, aber solange Du Dir damit kein Bein stellst - bitte sehr. Wenns dann mal soweit sein wird (und das wird es), kennst Du einen der Gründe aus eigener Erfahrung und ab dann wirst Du anders denken ;-)

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

Gruß
K-H

[sakura]

Zitat:

Zitat von BUG (Beitrag 1356534)

Zitat:

Zitat von Luckie (Beitrag 1356532)

Mit Kommentaren aufhübschen? Ein Widerspruch in sich. :?

Ich weiß nicht, wenn man sich in Legacy-Code einarbeitet, dann sind ein paar Kommentare/Notizen als erster Schritt sicher nicht die schlimmste Idee.

Wenn Luckies Aussage als "Blanket Statement" gemeint ist, dann: :shock:

Sollte es sich aber auf solche Dinge beziehen, dann:

Delphi-Quellcode:

// ==============================================================================================================================================
ganz viel code!
// ==============================================================================================================================================

Yes: :thumb:

Solche "Formatierungslinien" und Ähnliches sind für mich ein Graus, dann doch lieber Tools wie GExperts nutzen, die im Code-Editor die Abschnitte optisch hervorheben.

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

...:cat:...

[Stevie]

Zitat:

Zitat von sakura (Beitrag 1356717)

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:

Zitat von Stevie (Beitrag 1356718)

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.

...:cat:...

[Stevie]

Zitat:

Zitat von sakura (Beitrag 1356721)

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:

Zitat von sakura (Beitrag 1356721)

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:

Zitat von sakura (Beitrag 1356717)

Wenn Luckies Aussage als "Blanket Statement" gemeint ist, dann: :shock:

Ich denke mal nicht.
Mr. Puff zieht doch niemals blank.

Als Hauseigenes IDE-Feature (seit 'ner Weile) hat Region zwar optiosch nichts herzumachen ... im Gegenteil, es ist schon ein bissl unsichtbar, gegen sowas wie die zuvielen =============.
Aber es hat den selben Vorteil, wie alles in klassen zu packen.

Regionen kann man zusammenfalten. Da sieht man zwar den Code nicht besser, aber den anderern Code kann man schön wegblenden.
Auch kann man Funktionen über mehrere Klassen zusammenfassen und hat dann über den Klassenbrowser oder die Struktur auch einen Überblick.
Oder man kombiniert gleich Beides.

[Uwe Raabe]

Zitat:

Zitat von himitsu (Beitrag 1356725)

Regionen kann man zusammenfalten. Da sieht man zwar den Code nicht besser, aber den anderern Code kann man schön wegblenden.

Wenn man dann der Region noch einen sprechenden Namen gibt, dann sieht der zusammengeklappte Code fast so aus wie eine Reihe von parameterlosen Methodenaufrufen.

[himitsu]

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. :)

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;

[a.def]

Zitat:

Zitat von Stevie (Beitrag 1356718)

Zitat:

Zitat von sakura (Beitrag 1356717)

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/

Schon mehrfach selbst erlebt:
Projekte auf Seite geschoben, nach Monaten wieder ausgegraben und schon gingen die Hände an den Kopf da ich den Code von damals nicht mehr verstanden habe.

[Der schöne Günther]

Zitat:

Zitat von himitsu (Beitrag 1356728)

(Code)

Du hast

Delphi-Quellcode:

// **** Ab hier geht's los! ..... ****

vergessen

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

[sakura]

Zitat:

Zitat von bra (Beitrag 1356822)

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

Dem würde ich immer widersprechen. Unnötige Kommentare (ich rede noch nicht mal von fehlerhaften), kosten einfach nur unnötige Zeit, bei der Erstellung wie auch bei Code-Reviews und Nutzung.

...:cat:...