Wie und wieviel kommentiert Ihr Euren Code

[v2afrank]

Hallo,
wir haben ein Projekt an ein externes Softwareunternehmen vergeben und ich habe jetzt von denen den ersten Code bekommen.
Was mir aufgefallen ist, ist die Menge an Kommentaren, die fast gleich 0 ist. Laut Clean Code sollte das ja wohl auch der empfohlene Weg sein. Wir haben hier bei uns in der Firma selber Regeln aufgelegt wie Unitköpfe und Funktionen dokumentiert und kommentiert werden sollen. Jetzt interessiert mich einfach mal wie Ihr das so handhabt. Haltet Ihr Euch eher an das CleanCode Prinzip oder ???

[Valle]

Ich kommentiere relativ wenig. Methoden, deren Zweck nicht unmittelbar ersichtlich ist, werden im Code dokumentiert. Codestellen, die unerwartetes oder unverständliches tun auch. Ansonsten versuche ich den Code so zu schreiben dass er sprechend ist und nicht kommentiert werden muss.

[haentschman]

Moin...:P

[meine Meinung]
Ich halte die Kommentare bezüglich der History (Unitkopf, Procedurekopf) für überflüssig. :zwinker: Wenn man ein Versionskontrolsystem hat ist das doppelte Arbeit. Desweiteren sind sprechende Procedurnamen / Parameternamen das A + O. Da erübrigt sich meistens ein Kommentar. Persönlich sortiere ich meine Proceduren nach dem Typ... (...Eventhandler, Work, GUI Events, Actions etc.) :zwinker: Andere Suchen mit den Hilfsmitteln über den QT. Ich mag einfach keine Unordnung... :P
Wichtig allerdings ist das Kommentieren von Prozeduren bezüglich der Funktionsweise von Blöcken / einzelnen Zeilen z.B. wenn es notwendig erscheint.

...Also ich kommentiere dann nur wenn notwendig. :zwinker:
[/meine Meinung]

@Valle: +1

[himitsu]

Da alle meine Codes selbsterklärend und leicht verständlich sind, hab ich natürlich keinelei Kommentare im Code.



Spaß bei Seite.
Ich führe meine Dokumentation im Code, also sind mindestens an vielen Funktionen/Typen/Konstanten (im Interface) entsprechende PasDoc XMLDoc (Documentation Insight) und ich führe das aktuell auch für UnitHeader ein.

Im Code wird vorallem "schlecht" Erkennbares, sowie "komisches" und abweichendes Verhalten kommentiert, sowie "böse" Codeoptimierungen, wo ich den OriginalCode dahinter schreib, damit man versteht was gemacht wird.

Zitat:

Ich halte die Kommentare bezüglich der History (Unitkopf, Procedurekopf) für überflüssig

Historie mach ich auch nicht.

Bei Komponenten-Units steht im Kopf das zugehörige Projekt, sowie die Copyright/Lizenz (nur der Name und das Detailierte als Link)

Bei Prozeduren mach ich auch nicht mehr überall die Dokumentation dran (hatte ich mal angefangen, aber lass ich grade wieder von ab) ... Jupp, sprechende Bezeichner sind immer besser, aber machmal muß man einfach bissl was erklären.

[Der schöne Günther]

Ich habe nichts neues beizutragen, nur eine Frage in der Richtung:

Ich habe nie verstanden was es bringt eine Unit selbst zu kommentieren. Angenommen sie enthält entweder

1. Eine Klasse
2. Ein Interface und ein dazugehöriger Exception-Typ
3. Einen Haufen Nummern-Konstanten

Was sollte der Text in den ersten Zeilen der Unit einem erzählen können was man nicht auf den ersten Blick sieht?

[Nersgatt]

Ich mach es wie Valle. Mein Code ist wenig bis gar nicht Kommentiert. Nur, wenn es wirklich schwer zu durchschauende Stellen sind. Und die versuche ich soweit es geht zu vermeiden. In diese Vermeidung investiere ich durchaus auch einige Zeit.

Wenn die Fremdfirma die Funktionsköpfe etc. nach euren Regeln kommentieren soll, dann müsste das entsprechend im Vertrag geregelt werden.

[sakura]

Ich kann nicht verstehen, wenn jemand nicht oder nur wenig kommentiert.

Wie oben schon angemerkt, für zumindest protected und public/published Members und alles im Interface-Bereich, sollte man immer dokumentieren, damit die Nutzer dieser Schnittstellen in der Doku das gewünschte Verhalten sofort verstehen können. Dafür eignet sich natürlich XMLDoc-Styles.

Gerade wenn mehrere an einem Projekt arbeiten ist dieses unabdingbar. Natürlich kann man vieles leicht erkennen, wenn man sich den Quelltext anschaut, aber das kostet immer wieder Zeit, jedes Mal. Die Methoden kurz zu dokumentieren kostet nur einmal Zeit ;-)

Innerhalb von Methoden eignet es sich vor dem Erstellen des eigentlichen Codes in PDL (programm description language) kurz die gewünschte Logik zu schreiben und dann den Code zu schreiben. Das erleichtert das spätere Korrigieren von Fehlern in Logik und Implementierung ungemein.

Alles andere erachte ich inzwischen als wahrlich schlechten Stil, und davon habe ich genug hier vor mir :?

Insgesamt sollte die Dokumentation von Codes nicht im Wege stehen, sondern helfen. Insbesondere, wenn jemand anders mal am Code arbeiten muss. Selbst hundert leichte Methoden in einer Unit sind nur schwer zu verstehen, wenn man gar keine Marschrichtung kennt...

...:cat:...

[Mavarik]

Kommentare nur wenn der Code nicht auf den 1. Blick zeigt was Sache ist.

oder auch gerne mal Kommentare wie:

// Frank lass hier die Finger weg, Du hast schon 3x versucht das zu optimieren - es bringt nix...

Mavarik

[Mavarik]

Zitat:

Zitat von sakura (Beitrag 1349686)

Wie oben schon angemerkt, für zumindest protected und public/published Members und alles im Interface-Bereich, sollte man immer dokumentieren, damit die Nutzer dieser Schnittstellen in der Doku das gewünschte Verhalten sofort verstehen können. Dafür eignet sich natürlich XMLDoc-Styles.

Was ein Interface macht sollte man erkennen. Wichtiger finde ich es, welche möglichen Exceptions auftreten können.

[JasonDX]

Ich versuche mich prinzipiell daran zu orientieren:
Der Code erklärt selbst, was er macht. Kommentare ergänzen das Warum wenn erforderlich.

Im Bezug auf Dokumentation von Methoden und Klassen: Klassen haben bei mir seltenst Dokumentation; Methoden dokumentiere ich dann, wenn sie außerhalb der Klasse sichtbar sind. Dabei konzentriere ich mich auf Grenzfälle, Exceptions und nicht zwingend intuitive Verhaltensweisen.

[Sherlock]

Tja, selbsterklärender Code ist das hohe Ziel der Entwicklerschaft.

Allein, er ist es leider nur für ungefähr eine Woche. Darum gilt: Es gibt keinen selbsterklärenden Code. Jeder ist der Meinung super Code zu produzieren, der sogar in aller Regel tut was er soll. Nur wird dieser Code von Menschen mit unterschiedlichem Kenntnisstand sehr unterschiedlich wahrgenommen (vulgo: verstanden). Darum schreibe ich zumindest was der folgende Code tun soll. Das hilft beim schnellen Überfliegen ungemein, man muss nämlich nicht erst compilieren, sondern kann sich auf die Prosa verlassen. Und nein, ich schreibe keine Kommentare für

Delphi-Quellcode:

writeln('Hello World')

. ;)

Sherlock

[Delphi-Laie]

Ja, auch meine Wenigkeit ist in dieser Hinsicht eher ein ziemlicher, aber kein absoluter Faulpelz.

In dem Augenblick, in dem man den Code schreibt, ist einem der Grund dafür klar, das Kommentieren daher (erstmal) unnötig.

Man muß also zwei Hürden überwinden:

1. Man muß sich in diesem Augenblick (oder unmittelbar danach) bewußt werden, daß es ggf. mal wieder etwas zu kommentieren gibt.
2. Man muß entscheiden, ob und inwieweit der Code "selbsterklärend" ist - oder eben nicht. Das ist schwierig einzuschätzen, weil man selbst sein schlechtester Korrekturleser ist.

Oft wird diese Faulheit bestraft, indem man sich Tage bis Jahre später dann auch erst wieder mehr oder minder mühsam in seinen eigenen Code, zumindest Teile davon, meistens ziemlich mühsam hineindenken muß. Klar, man hat dabei einen Heimvorteil, der aber mit der Zeit schwindet.

[himitsu]

Bei API-Wrappern versuche ich mich grade an einer Dokumentation durch Attribute, wo z.B. DLL, wichtigste Exports und nötige Berechtigungen genannt werden.
Aktuell haben sie keinerlei Funktion, könnten aber in Zukunft ausgelesen werden.

ALLERDINGS geh ich da etwas vom Standard weg ... meine Attribute gelten auch für ALLES Nachfolgende, ab der Definition, innerhalb der Definitionsebene und nicht nur für die EINE Nachfolgende Methode/Typ.
=> nur das Nötigste und nicht alles mit Attributen vollgekleistert, sonst erkennt man den Code ja nicht mehr. :stupid: (ich hätte mir Postfix-Attribute gewünscht ... wie ein //-Kommentar, hinter die CodeZeile)

[Lemmy]

ich notiere mir die Verbindung zu externen Dokumenten wie Pflichtenheft / Anforderungskatalog, damit ich zum einen nachlesen kann warum der Code so ist wie er ist (hoffentlich) und zum anderen bei Änderungen an der Anforderung die relevanten Codestellen schnell finde.

Ansonsten dokumentiere ich dann, wenn ich denke, dass der folgende Code "unerwartet" ist - man könnte vermutlich auch sagen, dass solcher Code "riecht".

Als Ausnahme natürlich Interfaces wenn diese als Bibliothek auch anderen zur Verfügung gestellt werden, dann muss das per XMLDoc/Documentation Insight dokumentiert sein...

[SProske]

Ergänzend zu bisher genannten Punkten
- Berechnungsformeln (Herleitung, Leselinks etc.)
- Codeschnipsel die aus dem Web übernommen oder hergeleitet wurden
- Wenn ich irgendwo beim Debuggen ewig hing, versuche ich meine Erkentnisse zu dokumentieren (Refaktoring wäre natürlich besser, aber wann hat man shcon mal Zeit...)
- wenn Code für irgendwelche Sonderfälle angepasst werden musste -> Doku für diesen Sonderfall

[Nersgatt]

Wenn ich diesen Thread so lese, überkommt mich das Gefühl, dass für viele Leute "Kommentar" und "Dokumentation" das selbe zu sein scheint. Das finde ich interessant :cyclops:
Ohne hier jetzt irgendwie werten zu wollen, war mir das nicht bewusst, dass scheinbar viele Leute in diesem Aspekt nicht unterschieden.

[himitsu]

Jupp, Quellangaben von Fremdcodes, sind auch immer gut, wenn sie vor Ort dokumentiert sind. (nicht nur wegend der Lizenz, sondern auch für zukünftige Updates und Bugfixe)

[Sherlock]

Zitat:

Zitat von Nersgatt (Beitrag 1349707)

Wenn ich diesen Thread so lese, überkommt mich das Gefühl, dass für viele Leute "Kommentar" und "Dokumentation" das selbe zu sein scheint. Das finde ich interessant :cyclops:
Ohne hier jetzt irgendwie werten zu wollen, war mir das nicht bewusst, dass scheinbar viele Leute in diesem Aspekt nicht unterschieden.

Die Grenzen verschwimmen, wenn man ein Tool verwendet, daß aus dem Code die Dokumentation erzeugen soll.

Sherlock

[Aviator]

In neuen Programmen versuche ich im Interface Abschnitt die Methoden mit Hilfe von XML Dokumentation zu beschreiben. Auch die Parameter. Nichts desto trotz verwende ich sprechende Parameternamen um nicht immer wieder nachlesen zu müssen. Aber auch damit andere eine Methode aufrufen bzw. begutachten können wenn ich den Code weitergeben müsste.

Bei alten Projekten versuche ich neue Methoden immer etwas zu beschreiben. Die stechen dann zwar oft heraus weil sonst nix anderes Dokumentiert ist, aber immerhin besser als nichts. :stupid:

Kommentare verwende ich im Code ebenfalls wenn bestimmte Stellen sehr komplex sind und es einfach nicht besser/übersichtlicher zu programmieren ist.

Schlimm finde ich aber so Kommentare wie das bei Linux in manchen Konfigurationsdateien zu finden ist. Da wird erst 100 Zeilen Kommentar geschrieben und dann kommt die eigentlich eine (!) Zeile die eine Funktion hat. Das übersieht man dann einfach und wundert sich, wieso nix in der Datei drin steht was etwas bewirken könnte. :cyclops:

[p80286]

Wenn alles so läuft wie gedacht, bracht man keine Kommentare.
(Und die Erde ist eine Scheibe)

Bei der Durchsicht von alten Code-Friedhöfen ist mir aufgefallen wieviel Kontext für das Verständnis notwendig ist, und der fehlt nach ein paar Jahren. Es ist nicht selbstverständlich, daß

Delphi-Quellcode:

MWSF=11;

einen Mehrwertsteuerfaktor meint. Und wenn ein

Delphi-Quellcode:

GetCaseKey

heute noch sprechend ist, weil die Datenbank ein Feld CaseKey hat, dann ist das Morgen ein

Delphi-Quellcode:

GetCaseID

. Gut man könnte auch

Delphi-Quellcode:

GetCasePK

nutzen, aber was wenn es sich nicht um den PK handelt??

Gruß
K-H

[Luckie]

Ich versuche es auch so, dass der Code von alleine erklärend ist. Eine Versionshistory im Header kann, aber denn noch sinnvoll sein, wenn man den Code weggibt. Die haben dann ja meistens nicht den Verlauf im Repository. Ändere ich bestehenden Code von anderen kommt meist ein:

Delphi-Quellcode:

// MP start
// [Datum, Grund]
...;
...;
...;
// MP ende

in den Code. Dann kann man auf den ersten Blick nachvollziehen wer, was, wo warum geändert hat ohne alte Versionen erst vergleichen zu müssen.

[Benedikt Magnus]

Zitat:

Zitat von Aviator (Beitrag 1349720)

Schlimm finde ich aber so Kommentare wie das bei Linux in manchen Konfigurationsdateien zu finden ist. Da wird erst 100 Zeilen Kommentar geschrieben und dann kommt die eigentlich eine (!) Zeile die eine Funktion hat. Das übersieht man dann einfach und wundert sich, wieso nix in der Datei drin steht was etwas bewirken könnte. :cyclops:

Naja, das hat aber schon seinen Sinn. Denn diese hundert Zeilen beschreiben z.B. genau, was neben dieser einen folgenden Zeile noch alles möglich ist, wie es funktioniert und wann was sinnvoll ist. Stell dir vor, du kannst in einem Aufruf beispielsweise Dinge wie Dateisystem, Rechte, Anzahl Unterverzeichnisse etc. angeben. Aber standardmäßig steht diese Einstellung dann auf "auto" oder "none"... :wink:
Und diese Erklärung genau dorthin über die Einstellung zu packen halte ich für sehr viel praktischer als irgendwo in einer Dokumentation (die sich sonstwo finden lässt) danach zu suchen.

[striderx]

Von der IT eines großen Konzerns kenne ich Programmiervorgaben, die einen bestimmten Anteil von Kommentierungen einfordern (z. B. 20 Prozent des Quellcodes).

Der Hintergrund dafür: Geschäftskritische Anwendungen müssen auch wartbar sein, nachdem die ursprünglichen Entwickler nicht mehr zur Berfügung stehen. Des weiterem wird in diesem Bereich ja auch tailoristisch gestückelt und/oder nach draußen Vergeben - da ist es unabdingbar, dass mit vertretbarem Aufwand nachvollziehen kann, was in dem jeweiligen Segment los ist. Und ich bezweifele, dass man bei komplexen Anwendungen Sourcecode immer so schreiben kann, dass er leicht nachvollziehbar ist.

Anders sieht es natürlich aus, wenn man Einzelkämpfer ist. Dann kann man sich auch mit Nachrichten an sich selbst begnügen (siehe Post von Frank).

Und noch ein Gedanke: Nach meiner Erfahrung kann die Formulierung eines Kommentars durchaus noch einmal eine Art der Qualitätssicherung sein.

[dummzeuch]

Mein Problem mit Kommentaren ist, dass sie nicht gepflegt werden. Da beschreibt der Kommentar etwas voellig anderes als der Code und man sucht sich dumm und daemlich. Lieber kein Kommentar als ein falscher. Mir waere es wesentlich lieber, wenn meine Kollegen beim Commit eine sinnvolle Beschreibung ihrer Aenderungen eingeben wurden.

Die generelle Regel bei Komentaren sollte sein: Beschreibe das Warum, nicht das Was, es sei denn, es ist offensichtlich. Ueberarbeite lieber nochmal den den Code, um ihn verstaendlicher zu machen (Tipp: Sprechende Prozedur- und Variablennamen) als einen Kommentar zu schreiben.

Inc(i); // Wichtig: i um eins erhoehen

[mm1256]

Zitat:

Zitat von Luckie (Beitrag 1349727)

Ich versuche es auch so, dass der Code von alleine erklärend ist. Eine Versionshistory im Header kann, aber denn noch sinnvoll sein, wenn man den Code weggibt. Die haben dann ja meistens nicht den Verlauf im Repository. Ändere ich bestehenden Code von anderen kommt meist ein:

Delphi-Quellcode:

// MP start
// [Datum, Grund]
...;
...;
...;
// MP ende

in den Code. Dann kann man auf den ersten Blick nachvollziehen wer, was, wo warum geändert hat ohne alte Versionen erst vergleichen zu müssen.

Genauso handhabe ich das generell :thumb: nur meine Syntax ist etwas anders

Delphi-Quellcode:

...;
...; {!!.VERSION und alternativ das Datum}
...;

wobei VERSION die Versions-Nummer ist. Der praktische Vorteil kommt zum Tragen wenn man alle Änderungen einer bestimmten Version innerhalb eines Projektes im Suchfenster auflisten möchte, um dann schnell zu den Änderungen zu springen.

Übrigens, ich hab's nicht erfunden. Hab mir diese Praxis in den 90-er Jahren von TurboPower abgeguckt. Hat sich bis heute bestens bewährt 8-)

[Ghostwalker]

hmm...also...selbst mit rund 20 Jahren Erfahrung als Entwickler kann ich sagen, das ich bisher noch
kein wirklich optimales System gefunden habe.

Im moment arbeite ich so, das ich, im Quelltext selbst, soviel erkläre, wie notwendig, um zu verstehen was eine Methode macht. Komplexere Teile, die womöglich noch Zusammenhänge erklären sollen, werden nur mit einem Verweis gekennzeichnet, der in eine extra Doku läuft. Sachen, wie z.B. Versions-History oder Lizenz-Hinweise haben imho im Quelltext nix verloren, da sie keine Informationen zur Funktion des Quelltextes liefern. Auch sollten sinnlose Kommentare vermieden werden, wie z.B.:

Code:

   Procedure Foo();
   var
     i : integer;
   begin
     //i ist eine Schleifenvariable vom Typ integer
     for i := 1 to 10 do
     begin
        ...
     end;
   end;

(He...nicht lachen....sowas ist mir schon untegekommen:wink:)

[hoika]

Hallo,
also gerade wenn es eine Fremdfirma ist, finde ich eine Dokumentation im Quellcode sehr wichtig.
Also auch, was eine Methode macht, welche Parameter sie hat usw.
Das führt übrigens auch dazu, sich Gedanken bei der Entwicklung selbst zu machen,
schon allein, wenn man mit einem Satz schreiben soll, was sie macht.

Richtig ist, dass eine externe Dokumentation immer der Implementierung hinterherhinkt,
sobald die erste Änderung aufgetreten ist.

Sogar im eigenen Entwicklerkreis arbeitet doch mal jeder an einem anderen Code.
Ich neige dazu, bei kleineren Änderungen den alten Code auszuklammern und mit einzuchecken:

{ Entwickler-Kürzel, Datum, Version }
{ argz, was soll denn das -2 ??? }
//for i:= 0 to StringList.Count-2
for i:= 0 to StringList.Count-1
{ Ende: Kürzel, Datum Version }

Warum?
Weil ich bei 100 Änderungen an einer Datei mit jedem CVS ewig brauche,
um den Entwickler und das Datum zu erfinden, der eine bestimmte Änderung verbrochen hat.
Und der Debugger kann mir nicht sagen, wieso ein Code plötzlich funktioniert/nicht funktioniert,
indem er mir die Änderungen zur Vorversion anzeigt.

Von Zeit zu Zeit gehe ich die Quellcodes durch und lösche den alten auskommentierten Code.

So habe ich alles, was ich will:
den alten und neuen Code für eine Weile nebeneinander
nach einer Weile nur noch den neuen Code
die Änderungen pro Revision über das CVS in dem Diff

[BUG]

Zitat:

Zitat von hoika (Beitrag 1349764)

Richtig ist, dass eine externe Dokumentation immer der Implementierung hinterherhinkt,
sobald die erste Änderung aufgetreten ist.

Stimmt, und ehrlich gesagt sind sind die Teile, die ich in externer Doku unterbringe, nie Sachen die man einfach mal so ändert .. sondern eher größere Konzepte und Zusammenhänge. Auch kompliziertere Beweise, Laufzeitabschätzungen oder Benchmarkergebnisse würde ich nicht in Code haben wollen (hab aber auch eher selten).

Zitat:

Zitat von hoika (Beitrag 1349764)

{ Entwickler-Kürzel, Datum, Version }
{ argz, was soll denn das -2 ??? }
//for i:= 0 to StringList.Count-2
for i:= 0 to StringList.Count-1
{ Ende: Kürzel, Datum Version }

Gerade das Beispiel finde ich superunübersichtlich.

Zitat:

Zitat von hoika (Beitrag 1349764)

Weil ich bei 100 Änderungen an einer Datei mit jedem CVS ewig brauche,
um den Entwickler und das Datum zu erfinden, der eine bestimmte Änderung verbrochen hat.

Nur falls du es noch nicht kennst: die meisten SCM haben irgend eine Variante von Blame. In manchen Fällen kann das helfen.

Zitat:

Zitat von hoika (Beitrag 1349764)

Und der Debugger kann mir nicht sagen, wieso ein Code plötzlich funktioniert/nicht funktioniert,
indem er mir die Änderungen zur Vorversion anzeigt.

Git kann binäre Suche, aber dazu kann ich mich auch nie durchringen :wink:


Während des Arbeiten lass ich mir den alten Code auch gerne mal stehen (auch bei Zwischen-Commits), aber spätestens vor dem Merge mit dem Main-Branch fliegt dass alte Zeug weg.

[Ghostwalker]

Zitat:

Also auch, was eine Methode macht, welche Parameter sie hat usw.

Das sollte man eigentlich am Quelltext ablesen können (Stichwort sprechende Bezeichner). Viel wichtiger ist, den Gedankengang hinter der Implementierung kurz zu erläutern.

Zitat:

Code:

{ Entwickler-Kürzel, Datum, Version }
{ argz, was soll denn das -2 ??? }
//for i:= 0 to StringList.Count-2
for i:= 0 to StringList.Count-1
{ Ende: Kürzel, Datum Version }

Auch das ist, imho kein so gutes Beispiel, da die Gefahr besteht, das im laufe der Zeit so etwas daraus entsteht:

Code:

{ AM, 01.03.2010, 1.0 }
{ argz, was soll denn das -2 ??? }
{ BM, 05.03.2010, 1.1 }
( Überladene Version von Stringlist )
{ AM, 10.03.2010, 1.2 }
{ -2 führt aber zu einem Zugriffsfehler }
{ BM, 12.03.2010, 1.3 }
( Unit an der falschen Stelle )
for i:= 0 to StringList.Count-2
//for i:= 0 to StringList.Count-1
{ AM, 01.03.2010, 1.0 }
{ BM, 05.03.2010, 1.1 }
{ AM, 10.03.2010, 1.2 }
{ BM, 12.03.2010, 1.3 }

Das ist so ein Beispiel wo man vor lauter Kommentar, den Quelltext nicht mehr erkennt :)

Zitat:

Weil ich bei 100 Änderungen an einer Datei mit jedem CVS ewig brauche,
um den Entwickler und das Datum zu erfinden, der eine bestimmte Änderung verbrochen hat.

Der "Schuldige" und das Datum nützen (aus meiner Erfahrung) nur selten etwas, insbesondere
wenn selbiger nicht mehr für die Firma tätig ist. Und selbst wenn er noch Verfügbar ist, wird
er dir auch nicht sagen können warum er das vor 2 Jahr so oder so gemacht hat. :)

Zitat:

Und der Debugger kann mir nicht sagen, wieso ein Code plötzlich funktioniert/nicht funktioniert,
indem er mir die Änderungen zur Vorversion anzeigt.

Das kann dir im Regelfall keiner sagen. Richtig gepflegt, zeigt dir die Vorversion an was anders gemacht wurde und bringt dich u.U. darauf, wo das Problem zu suchen ist.


Ob ein Kommentar sinnvoll und nützlich ist, ist von sehr vielen Faktoren abhängig. Ich denke eine generelle Lösung gibts da einfach nicht. :)

[Der schöne Günther]

Zitat:

Zitat von hoika (Beitrag 1349764)

Warum?
Weil ich bei 100 Änderungen an einer Datei mit jedem CVS ewig brauche,
um den Entwickler und das Datum zu erfinden, der eine bestimmte Änderung verbrochen hat.

Nur als Hinweis: Selbst für das RAD Studio gibt es z.B. die "Blame Bar" welche dir, egal ob SVN, Git oder HG, zu jeder Zeile sagen kann wer es verbrochen hat - Steht einfach links neben der Zeilennummer der Name. Fährt man mit der Maus drüber siehst du das Datum und den Checkin-Kommentar. Der beinhaltet ja die Motivation was diese Änderung im großen Kontext bewirken sollte.

Alte Bestandteile ausklammern im Code lassen - Niemals. Würde ich nur zulassen wenn es ein historischer Fehler ist der 10 Jahre lang ausgeliefert wurde und jetzt das bestehende Verhalten (zumindest im internen Ablauf) ändert.

Hoppla, der Hinweis mit Blame kam schon.

[himitsu]

Zitat:

Zitat von hoika (Beitrag 1349764)

Weil ich bei 100 Änderungen an einer Datei mit jedem CVS ewig brauche,
um den Entwickler und das Datum zu erfinden, der eine bestimmte Änderung verbrochen hat.

Die guteren CVS sagen dir aber wer welche Zeile zuletzt eingecheckt hat.
Bei SVN nennt sich das Blame (Schuld).



Hab extra das Wort "Besser" vermieden :stupid:

[Jim Carrey]

Zitat:

{ Entwickler-Kürzel, Datum, Version }
{ argz, was soll denn das -2 ??? }
//for i:= 0 to StringList.Count-2
for i:= 0 to StringList.Count-1
{ Ende: Kürzel, Datum Version }

Was ist denn, wenn Entwickler 2 innerhalb der Schleife etwas abändert?
Er darf dann ja nicht als Entwickler der kompletten Schleife angegeben werden.

Das würde zu einer großen Unübersichtlichkeit führen meiner Meinung nach.

[Sailor]

Knuth hatte da mal in den 90igern was, nannte sich "Literate Programming" mit Hilfe von WEB. Die Idee war, einen Text zu schreiben, aus dem durch Übersetzung sowohl der Programmtext als auch die Dokumentation erzeugt wurden. Ich habe das mal versucht, aber dann entnervt aufgegeben. Allerdings könnte das heute mit modernen Editoren, Displays und schnellen Rechnern anders aussehen. Müßte man sich mal wieder ansehen.

[himitsu]

Zitat:

Zitat von Sailor (Beitrag 1349822)

Die Idee war, einen Text zu schreiben, aus dem durch Übersetzung sowohl der Programmtext als auch die Dokumentation erzeugt wurden.

Das nennt sich Shakespeare Programming Language :lol:

https://de.wikipedia.org/wiki/Shakes...mming_Language
https://de.wikipedia.org/wiki/Esoter...rammiersprache
https://de.wikipedia.org/wiki/Liste_...ammen/Sonstige

Die Pascal-Syntax an sich ist selber auch so entworfen, damit man dass schreibt, was man machen will.

[p80286]

Zitat:

Zitat von Jim Carrey (Beitrag 1349804)

Delphi-Quellcode:

{ Entwickler-Kürzel, Datum, Version }
{ argz, was soll denn das -2 ??? }
//for i:= 0 to StringList.Count-2
for i:= 0 to StringList.Count-1
{ Ende: Kürzel, Datum Version }

Was ist denn, wenn Entwickler 2 innerhalb der Schleife etwas abändert?
Er darf dann ja nicht als Entwickler der kompletten Schleife angegeben werden.

Das würde zu einer großen Unübersichtlichkeit führen meiner Meinung nach.

Im Prinzip halte ich das für sehr gut, nur die Umsetzung ist nicht so dolle.

Delphi-Quellcode:

//for i:= 0 to StringList.Count-2  { argz, was soll denn das -2 ??? } { Entwickler-Kürzel, Datum, Version }
for i:= 0 to StringList.Count-1

Ist meiner Meinung nach ausreichend. GGF. kann man auch die Vereinbarung treffen, das ersetzte Code Teile mit

Delphi-Quellcode:

(* *)

auskommentiert werden.

Gruß
K-H

[jaenicke]

Zitat:

Zitat von striderx (Beitrag 1349752)

Von der IT eines großen Konzerns kenne ich Programmiervorgaben, die einen bestimmten Anteil von Kommentierungen einfordern (z. B. 20 Prozent des Quellcodes).

Der Hintergrund dafür: Geschäftskritische Anwendungen müssen auch wartbar sein, nachdem die ursprünglichen Entwickler nicht mehr zur Berfügung stehen.

Dafür sind solche Vorgaben oft genau nicht geeignet. Ich habe schon solche Projekte gesehen. Da wurde dann um die Quote zu erfüllen extra kommentiert, dass eine Schleife für jeden Eintrag einmal durchlaufen wird usw., dafür wurden Variablennamen oft nur mit einem Zeichen geschrieben. Denn die Erklärung steht ja im Kommentar.
Das macht den Quelltext dann deutlich schlechter lesbar und extrem schlecht zu warten.

Deshalb stammen solche Vorgaben oft aus dem Management und nicht von denjenigen, die damit arbeiten. Um es mal vorsichtig auszudrücken. ;-)

Viel wichtiger als Kommentare oder Dokumentationen der einzelnen Routinen ist erst einmal eine Gesamtdokumentation, in der drin steht wie das ganze Projekt organisiert ist, wie die Abläufe grundsätzlich sind (Pattern, Dateiorganisation, ...), usw.

Denn wenn der Quelltext sauber geschrieben wurde, lese ich den Code eher schneller als jede Dokumentation. Wenn ich aber keinen Grundfahrplan habe wie das Projekt aufgebaut ist, finde ich mich erst einmal schlecht in das Projekt hinein. Und das kostet dann wirklich sehr viel Zeit.

Zitat:

Zitat von himitsu (Beitrag 1349794)

Die guteren CVS sagen dir aber wer welche Zeile zuletzt eingecheckt hat.
Bei SVN nennt sich das Blame (Schuld).

Und man kann dann auch von dort aus die vorherige Änderung der Zeile suchen usw., egal ob bei Git, Mercurial, SVN, ...

[hoika]

Hallo,
ich hatte ja gesagt, dass die auskommentierten Änderungen auch mal gelöscht werden.
Das mit dem Blame habe ich so nicht verstanden ...
Wir haben SVN, mal im RedBook lesen.

Trotzdem möchte ich durch Lesen des Quellcodes sofort wissen, wann wer für welche Version das eingebaut hat.
Und Version muss nicht mit der SVN-Branch ocer SVN-Tag übereinstimmen.

Aber das soll jeder ja so machen, wie er es gewohnt, versteht oder es gefordert wird.

http://svnbook.red-bean.com/de/1.7/s...n.c.blame.html
Nun ja, so gut ist das dann doch nicht (Stichwort Leerzeichen korrigiert).
Aber für sowas haben wir ja eh keine Zeit ;)

[Rollo62]

Zitat:

ch hatte ja gesagt, dass die auskommentierten Änderungen auch mal gelöscht werden.

+1

Das finde ich während der Entwicklung, in dem jede Menge Tests gemacht werden völlig OK.
Gelöschte Tests wiederherzustellen ist viel problematischer als sie einfach wegzukommentieren.

Guter Stil hin, schlechter Stil her: Ich mache das was mich schneller zum Ziel bringt, auch wenn's nicht immer hübsch aussieht :stupid:

Rollo

[striderx]

"Real programmers don’t document. If it was hard to write, it should be hard to understand."

"Documentation is like sex: when it is good, it is very, very good; and when it is bad, it is better than nothing."


Wie viele schöne andere Sprüche zu finden auf

https://henrikwarne.com/2016/04/17/m...amming-quotes/