AGB  ·  Datenschutz  ·  Impressum  







Anmelden
Nützliche Links
Registrieren
Zurück Delphi-PRAXiS Programmierung allgemein Programmieren allgemein Wie und wieviel kommentiert Ihr Euren Code

Wie und wieviel kommentiert Ihr Euren Code

Ein Thema von v2afrank · begonnen am 4. Okt 2016 · letzter Beitrag vom 12. Okt 2016
Antwort Antwort
Seite 3 von 4     123 4   
Benutzerbild von Luckie
Luckie

Registriert seit: 29. Mai 2002
37.621 Beiträge
 
Delphi 2006 Professional
 
#21

AW: Wie und wieviel kommentiert Ihr Euren Code

  Alt 4. Okt 2016, 16:53
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.
Michael
Ein Teil meines Codes würde euch verunsichern.
  Mit Zitat antworten Zitat
Benedikt Magnus

Registriert seit: 6. Jul 2012
Ort: Bonn
190 Beiträge
 
FreePascal / Lazarus
 
#22

AW: Wie und wieviel kommentiert Ihr Euren Code

  Alt 4. Okt 2016, 17:22
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.
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"...
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.
  Mit Zitat antworten Zitat
striderx

Registriert seit: 11. Feb 2007
Ort: Bergisch Gladbach
206 Beiträge
 
Delphi 10.4 Sydney
 
#23

AW: Wie und wieviel kommentiert Ihr Euren Code

  Alt 4. Okt 2016, 19:18
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.
  Mit Zitat antworten Zitat
Benutzerbild von dummzeuch
dummzeuch

Registriert seit: 11. Aug 2012
Ort: Essen
1.449 Beiträge
 
Delphi 10.2 Tokyo Professional
 
#24

AW: Wie und wieviel kommentiert Ihr Euren Code

  Alt 4. Okt 2016, 20:34
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
Thomas Mueller
  Mit Zitat antworten Zitat
mm1256

Registriert seit: 10. Feb 2014
Ort: Wackersdorf, Bayern
640 Beiträge
 
Delphi 10.1 Berlin Professional
 
#25

AW: Wie und wieviel kommentiert Ihr Euren Code

  Alt 4. Okt 2016, 20:58
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 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
Gruss Otto
Wenn du mit Gott reden willst, dann bete.
Wenn du ihn treffen willst, schreib bei Tempo 220 eine SMS
  Mit Zitat antworten Zitat
Ghostwalker

Registriert seit: 16. Jun 2003
Ort: Schönwald
1.299 Beiträge
 
Delphi 10.3 Rio
 
#26

AW: Wie und wieviel kommentiert Ihr Euren Code

  Alt 4. Okt 2016, 23:03
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)
Uwe
e=mc² or energy = milk * coffee²
  Mit Zitat antworten Zitat
hoika

Registriert seit: 5. Jul 2006
Ort: Magdeburg
8.269 Beiträge
 
Delphi 10.4 Sydney
 
#27

AW: Wie und wieviel kommentiert Ihr Euren Code

  Alt 4. Okt 2016, 23:48
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
Heiko
  Mit Zitat antworten Zitat
Benutzerbild von BUG
BUG

Registriert seit: 4. Dez 2003
Ort: Cottbus
2.094 Beiträge
 
#28

AW: Wie und wieviel kommentiert Ihr Euren Code

  Alt 5. Okt 2016, 01:30
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).

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

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.

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


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.
Intellekt ist das Verstehen von Wissen. Verstehen ist der wahre Pfad zu Einsicht. Einsicht ist der Schlüssel zu allem.

Geändert von BUG ( 5. Okt 2016 um 01:33 Uhr)
  Mit Zitat antworten Zitat
Ghostwalker

Registriert seit: 16. Jun 2003
Ort: Schönwald
1.299 Beiträge
 
Delphi 10.3 Rio
 
#29

AW: Wie und wieviel kommentiert Ihr Euren Code

  Alt 5. Okt 2016, 09:13
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.
Uwe
e=mc² or energy = milk * coffee²
  Mit Zitat antworten Zitat
Der schöne Günther

Registriert seit: 6. Mär 2013
6.093 Beiträge
 
Delphi 10 Seattle Enterprise
 
#30

AW: Wie und wieviel kommentiert Ihr Euren Code

  Alt 5. Okt 2016, 09:55
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.
  Mit Zitat antworten Zitat
Themen-Optionen Thema durchsuchen
Thema durchsuchen:

Erweiterte Suche
Ansicht

Forumregeln

Es ist dir nicht erlaubt, neue Themen zu verfassen.
Es ist dir nicht erlaubt, auf Beiträge zu antworten.
Es ist dir nicht erlaubt, Anhänge hochzuladen.
Es ist dir nicht erlaubt, deine Beiträge zu bearbeiten.

BB-Code ist an.
Smileys sind an.
[IMG] Code ist an.
HTML-Code ist aus.
Trackbacks are an
Pingbacks are an
Refbacks are aus

Gehe zu:

Impressum · AGB · Datenschutz · Nach oben
Alle Zeitangaben in WEZ +1. Es ist jetzt 09:08 Uhr.
Powered by vBulletin® Copyright ©2000 - 2024, Jelsoft Enterprises Ltd.
LinkBacks Enabled by vBSEO © 2011, Crawlability, Inc.
Delphi-PRAXiS (c) 2002 - 2023 by Daniel R. Wolf, 2024 by Thomas Breitkreuz