Quellcode Kommentieren

[Dejan Vu]

Ich arbeite als Architekt, Review und Entwickler, letzteres immer weniger.

Es ist nicht mehr Arbeit, wenn man die Methoden auf "3-Zeiler" herunterbricht. Im Gegenteil: Eine Umsetzung ist so wirklich viel viel schneller, weil sie meistens auf Anhieb läuft (bis auf die üblichen Schusseligkeitsfehler). Natürlich: Ich mach das seit Ewigkeiten (vor 30 Jahren jieß0 das Top-Down und 'stepwise refinement')und ich denke gar nicht mehr darüber nach, aber jedesmal, und wirklich jedes Mal, wenn ich in alte Ich-frickel-mir-schnell-Code-zusammen-ist-doch-wurscht-wie-das-aussieht verfalle, verfluche ich nach spätestens drei Erweiterungen mein anfängliches Gewurschtele.

Mein Tipp an Alle: Fangt mit Clean Code an. Nicht bis zum bitteren Ende, aber so, das man keine Kommentare benötigt, die den Code erklären. Der Code muss sich selbst erklären. Im Idealfall muss das ein englischer Satz (oder maximal 3-5) sein. 'If the customer is valid, then charge fees' ist wirklich 1:1 in Delphi abbildbar (das 'the' kann man weglassen). Schade, das es Linq für Delphi nicht gibt, da geht das noch besser.

Ach, und natürlich benötigt man richtiges Werkzeug. Ich bin auf C# umgestiegen und arbeite mit Resharper, da kann man sehr viel Refactoring ratzfatz schnell durchziehen. Codeschnipsel markieren => Methode extrahieren => Parameter benennen => fertig. Geht so -glaube ich- nicht in Delphi, oder?

[Stevie]

Zitat von Dejan Vu:

Schade, das es Linq für Delphi nicht gibt, da geht das noch besser.

Ach, und natürlich benötigt man richtiges Werkzeug. Ich bin auf C# umgestiegen und arbeite mit Resharper, da kann man sehr viel Refactoring ratzfatz schnell durchziehen. Codeschnipsel markieren => Methode extrahieren => Parameter benennen => fertig. Geht so -glaube ich- nicht in Delphi, oder?

Du hast gerade den Hauptgrund genannt, warum sich diese Cleancode Mentalität in der Delphi Community noch nicht so stark verbreitet hat, wie in anderen Sprachen. Unsere Tools dafür sind teilweise einfach Grütze.

[Sherlock]

Zitat von Stevie:

Zitat von Dejan Vu:

Schade, das es Linq für Delphi nicht gibt, da geht das noch besser.

Ach, und natürlich benötigt man richtiges Werkzeug. Ich bin auf C# umgestiegen und arbeite mit Resharper, da kann man sehr viel Refactoring ratzfatz schnell durchziehen. Codeschnipsel markieren => Methode extrahieren => Parameter benennen => fertig. Geht so -glaube ich- nicht in Delphi, oder?

Du hast gerade den Hauptgrund genannt, warum sich diese Cleancode Mentalität in der Delphi Community noch nicht so stark verbreitet hat, wie in anderen Sprachen. Unsere Tools dafür sind einfach Grütze.

Amen!

Sherlock

[Dejan Vu]

Zitat von Stevie:

Du hast gerade den Hauptgrund genannt, warum sich diese Cleancode Mentalität in der Delphi Community noch nicht so stark verbreitet hat, wie in anderen Sprachen. Unsere Tools dafür sind einfach Grütze.

Na ja. 20 Jahre Pascal mit top-down gingen auch ohne refactoring Tools.

Am Code herumkneten, bis er noch besser wird (speziell Bezeichner umbenennen)... stimmt, Codepflege und die Pfadfindermentalität: Geht ohne Tools wirklich nicht/bzw. schlecht.

Aber stepwise refinement, Probleme in kleine Probleme zu unterteilen, am Anfang abstrakt und erst zum schluß konkret zu werden, also lesbaren Code zu schreiben: Das mache ich schon immer so. Und vor ein paar Jahren hab ich dann gelesen, das das wohl en vogue ist.

[himitsu]

Zitat von hoika:

Hallo,

auch ich bin der Meinung, dass JEDE Methode kommentiert sein muss.
Spätestens, wenn sich jemand in etwas einarbeiten soll, ist das wichtig.
Allerdings ist der Kommentar der Methode ein Sache,
weit wichtiger sind aber die Parameter- und Returnwertbeschreibung.
Ich halte mich übrigens an die Syntax von DelphiCode2Doc.

Ich hab das die letzten Wochen auch mal bei einem Projekt gemacht, womit alleine das Unit-Interface von knapp 280 auf über 1800 Zeilen angewachsen ist, aber zum Glück kann man die sich Teile ausblenden zusammen falten lassen. (inzwischen über 3300 Zeilen, aber ich weiß jetzt nicht wie viel davon Code und wie viel Kommentare/Dokumentation sind)

Zitat von hoika:

Bsp:

Delphi-Quellcode:

{*
  vergleicht 2 Strings, ohne Groß- und Kleinschreibung zu beachten

  @param  S1  erster String
  @param  S2  zweiter String
  @return  <1 S1<S2, >1 S1>S2, =0 S1=S2
}
function CompareText(const S1, S2: String): Integer;

Ich bin selber mal in die Falle getappt, dass ich auf -1 geprüft habe, statt auf <1

Dass man aus diesen Kommentaren auch schön eine Dokumentation rausziehen kann,
also die Code-Beschreibung nicht doppelt schreiben muss, ist ein angenehmer Zusatznutzen.

PS: Es gibt dafür auch Konstanten, welche man verwenden könnte.

Delphi-Quellcode:

type
  TValueRelationship = -1..1;

const
  LessThanValue = Low(TValueRelationship);
  EqualsValue = 0;
  GreaterThanValue = High(TValueRelationship);

Mit DelphiCode2Doc nimmst du dir aber eine nette Funktion weg, welche es seit 2005/2006 im Delphi gibt.
=> Help-Insight

Und Delphi kann das inzwischen (XE2/XE3) selber zusammenfalten, ohne daß man die Regionen dafür benötigt.

Zitat:

Ach, und natürlich benötigt man richtiges Werkzeug. Ich bin auf C# umgestiegen und arbeite mit Resharper, da kann man sehr viel Refactoring ratzfatz schnell durchziehen. Codeschnipsel markieren => Methode extrahieren => Parameter benennen => fertig. Geht so -glaube ich- nicht in Delphi, oder?

Doch. (teilweise)

Refactoring > Methode Extrahieren
uvm., auch von Fremdanbietern (GExperts, cnPack, ...)

[JasonDX]

Zitat von Sherlock:

Dann jetzt mal Spaß beiseite: Bist Du hauptberuflicher Codereviewer? Weil das Zeitargument ist für mich äusserst nachvollziehbar

Das ist eine reine Prioritäts-(und damit auch Management)-Frage. Tests sind ein ähnliches Zeitinvestment. Ich verbringe einiges an Zeit damit, Tests zu schreiben, und anderer Leute Code zu reviewen - aber das ist auch gut so. Da wird dann gern auch auf mangelnde, falsche oder unnütze Dokumentation hingewiesen. Das Problem das ich mit CodeReviews in anderen Firmen gesehen habe ist eher das, dass manche Entwickler nicht so gut mit Kritik an deren Implementierungen zurechtkommen.

[Dejan Vu]

Zitat von JasonDX:

...Das Problem ..ist .., dass manche Entwickler nicht so gut mit Kritik an deren Implementierungen zurechtkommen.

Jupp. Daher kritisiere ich direkt nur unter vier Augen und immer konstruktiv und positiv und, wenn im Meeting, immer anonym aber auch nur dann, wenn der keine Mimose ist. Denn er/sie fühlt sich ja angesprochen. Ich versuche, den Narzißmus und die Empfindlichkeit durch (hört sich blöd an) teambildende Maßnahmen zu minimieren. Von einem 'Freund' lässt man sich eher etwas erzählen, als von einem Konkurrenten. Ich unterstütze Teamprogramming und 'sich gegenseitig helfen'.
Ich habe aber das Glück, das das Team fast nur aus kompetenten Leuten besteht, die sich teilweise noch aus der Schule kennen und die Chemie stimmt einfach.

[p80286]

Zitat von Dejan Vu:

...wenn ich in alte Ich-frickel-mir-schnell-Code-zusammen-ist-doch-wurscht-wie-das-aussieht verfalle, verfluche ich nach spätestens drei Erweiterungen mein anfängliches Gewurschtele.

Na, die Erfahrung sollten eigentlich die meisten von uns schon gemacht haben.


Übrigens sind die Namen der Prozeduren beim Erstellen meist sehr einleuchtend und präzise. Nach einem Monat sehe ich das für mich doch etwas kritischer.

Gruß
K-H

[Stevie]

Zitat von p80286:

Zitat von Dejan Vu:

...wenn ich in alte Ich-frickel-mir-schnell-Code-zusammen-ist-doch-wurscht-wie-das-aussieht verfalle, verfluche ich nach spätestens drei Erweiterungen mein anfängliches Gewurschtele.

Na, die Erfahrung sollten eigentlich die meisten von uns schon gemacht haben.

Witzigerweise ist das aber die Argumentation, die ich oft höre, wenn es um sauberen Code, Einhaltung von bestimmten Praktiken etc geht. Für kleine Huschhusch Projekte oder irgendwas, was man nur alleine programmiert, braucht man sowas ja nicht... ja, nee is klar. Wenn man das schon nicht für nen banales Projekt macht und dort lernt, dann wird man das bestimmt bei nem Riesenprojekt perfekt beherrschen.

[OlafSt]

Clean Code lohnt sich auch auf andere, ungewöhnlichere Art:

Noch im letzten Jahrtausend (OMG, wie sich das anhört) schrieb ich eine Applikation, die via GSM-Modem irgendwo Daten abholte, decodierte und in einer SQL-DB verschwinden ließ. ich wechselte die Firma, wechselte die Firma, wechselte die Firma, lag im KH, machte mich selbständig.

Dann klingelt das Telefon - der Kunde von damals möchte ein paar Änderungen an dem Ding haben. 15 Jahre alter D7-Code. Da bist du froh, wenn du sauber gearbeitet und ein paar Kommentare hinterlassen hast.