Quellcode Kommentieren

[franktron]

Ich hatte mal eine Erweiterung die das machte

Bsp.
//*******************************
//Procedurenname Param1 Param1
//Erstallt am xx.xx.xxxx von Frank
//Geändert am xx.xx.xxxx von Frank
//***********************************

[bernau]

Zitat von franktron:

Ich hatte mal eine Erweiterung die das machte

Bsp.
//*******************************
//Procedurenname Param1 Param1
//Erstallt am xx.xx.xxxx von Frank
//Geändert am xx.xx.xxxx von Frank
//***********************************

GExperts kann so etwas. Nutze ich permanent.

[franktron]

Zitat von bernau:

Zitat von franktron:

Ich hatte mal eine Erweiterung die das machte

Bsp.
//*******************************
//Procedurenname Param1 Param1
//Erstallt am xx.xx.xxxx von Frank
//Geändert am xx.xx.xxxx von Frank
//***********************************

GExperts kann so etwas. Nutze ich permanent.

Wo ? ich hab den

[bernau]

Menü->GExperts->Editor Experts->Expand Macro Templates

Oder Shift-Alt-T

Dann aus der Liste "Procedure Header" auswählen. Kannst du natürlich anpassen.

[sx2008]

Also bei uns in der Abteilung war das auch mal schwer in Mode *grundsätzlich* vor jede Funktion/Procedure/Methode einen Kommentarblock zu setzen.
Aber wenn man mal darüber nachdenkt, kommt man drauf dass das eigentlich ziemlich dumm ist.
Denn meistens steht im Kommentar nicht mehr als in der Funktion selber.
Wann eine Funktion erstellt und geändert wurde ist relativ uninteressant werden man eine Versionsverwaltung verwendet.
Und wenn man keine Versionsverwaltung hat dann wird's aber höchste Eisenbahn.

Die Nachteile der Zwangskommentare sind:
* Zeitverschwendung durch Einfügen und Pflegen von Kommentaren die keinen Zusatznutzen bringen
* visuelles Störfeuer - je mehr Zeichen auf dem Bildschirm sind umso mehr Kapazität benötigt das menschliche Gehirn um Wichtiges von Unwichtigem zu trennen
* die Stellen die wirklich mal einen Kommentar haben fallen gar nicht auf weil überall Kommentare stehen
* anstatt darüber nachzudenken wie man die Funktionen sprechender machen könnte verlässt man sich auf nutzlose Kommentare die im Zweifelsfall doch eh falsch sind weil sich Funktionsname und/oder Parameter geändert haben

Meine Empfehlung:
vor wichtigen/komplizierten/erklärungsbedüftigen Funktionen schreibt man eine Kommentarezeile die kurz beschreibt was die Funktion macht.
Hier ein Beispiel:

Delphi-Quellcode:

// wandelt einen Speicherbereich in einen hexadezimalen String
function BufferToHexString(buffer:Pointer;size:Integer):AnsiString;
begin
   if not Assigned(buffer) or (size<=0) then
      Result := ''
   else
   begin
      SetLength(Result, size*2);
      BinToHex(PChar(buffer), PChar(Result), size);
   end;
end;

Wobei in obigem Beispiel der Funktionsname schon so sprechend ist dass man auf den Kommentar auch verzichten könnte.
Mehr als eine Zeile zu schreiben ist nicht verboten!

[mjustin]

Zitat von sx2008:

Die Nachteile der Zwangskommentare sind:
* Zeitverschwendung durch Einfügen und Pflegen von Kommentaren die keinen Zusatznutzen bringen

Mein Lieblingsbeispiel für Kommentare ohne Zusatznutzen:

Delphi-Quellcode:

  TForm1 = class(TForm)
  private
    { Private declarations }
  public
    { Public declarations }
  end;

[bernau]

Zitat von sx2008:

Die Nachteile der Zwangskommentare sind:
* Zeitverschwendung durch Einfügen und Pflegen von Kommentaren die keinen Zusatznutzen bringen
* visuelles Störfeuer - je mehr Zeichen auf dem Bildschirm sind umso mehr Kapazität benötigt das menschliche Gehirn um Wichtiges von Unwichtigem zu trennen
* die Stellen die wirklich mal einen Kommentar haben fallen gar nicht auf weil überall Kommentare stehen
* anstatt darüber nachzudenken wie man die Funktionen sprechender machen könnte verlässt man sich auf nutzlose Kommentare die im Zweifelsfall doch eh falsch sind weil sich Funktionsname und/oder Parameter geändert haben

Visuelles Störfeuer: Ich finde es sehr angenehm, wenn zwischen Proceduren ein "erkennbarer Block" steht, der zwei Proceduren voneinander trennt.
Eine Schnelle Info, wann diese Procedure angelegt wurde finde ich auch sehr gut. Benutze zwar ein Versionscontrolsystem. Aber das würde unnötige klicks benötigen.
Kommentare stehen im Procedure-Header nur, wenn es tatsächlich etwas wichtiges zu beachten gibt.

[Dejan Vu]

Zitat von bernau:

Ich finde es sehr angenehm, wenn zwischen Proceduren ein "erkennbarer Block" steht, der zwei Proceduren voneinander trennt.

Da reicht dann aber ein '(****** ... ****)' o.ä. Wenn's denn sein muss (ich finds grauslig).

Wenn man eine Methode kommentieren muss, ist sie zu lang, hat einen falschen Namen oder beides. Nur wenn ich z.B. eine Gesetzesvorlage (oder eine Spec) explizit umsetze, oder eine mathematische Formel/Verfahren etwas komplexeren Ausmaßes, kommt ein kurzer Kommentar rein mit Quelle.

Kommentare sind böse und lügen. Einfach mal 'Clean Code' lesen, dann weiß man, was ich meine. sx2008 hat das meiste ja schon erklärt.