Quellcode Kommentieren

[mjustin]

Zitat von bernau:

Zitat von Dejan Vu:

Zitat von bernau:

Aber manchmal gibt es "unsinnige Wünsche" von Kunden. So etwas kommentiere ich immer. Teilweise sogar mit Verweis auf die E-Mail des Kunden.

Wir machen das über CVS.

Das interessiert mich. Wie sieht das in der Praxis aus? Der Hinweis auf den Kundenwunsch steht bei mir im Code und fällt sofort in's Auge. Wie sieht das im CSV aus? Wo steht der Hinweis? Muss ich selber aktiv einen Button drücken um diese Zusatzinfo zu sehen?

Delphi-Quellcode:

Procedure ZeigMalWas;
begin
  // 10.10.2012 - E-Mail von Meyer - Will ein Blinken im Sekundentakt.
  // LassBlinken(1);
  // 20.11.2012 - E-Mail von Müller - Blinken zu hektisch. Auf Wunsch nur alle 2 Sekunden.
  // LassBlinken(2);
  // 20.03.2013 - Telefonat mit Meyer - Vertrieb hat sich durchgesetzt. Blinken 2 mal pro Sekunde.
  LassBlinken(0.5);
end;

Ich kenne kein Versionskontrollsystem oder eine CSV-IDE Integration sie so etwas kann oder nur in die Nähe käme.

Alle gängigen Systeme (Git, SVN etc.) arbeiten dateiorientiert. Man kann sich also zu der Unit, in der Procedure Machwas enthalten ist, detailliert auflisten lassen wer wann und warum etwas an der Unit geändert hat. Sich aber nur auf Prozedurebene die Änderungen anzeigen zu lassen, ist mit den mir bekannten Werkzeugen nicht möglich. Müßte man mal recherchieren

Aber selbst wenn es möglich wäre, aus dem Versionskontrollsysteme ein Änderungsprotokoll einer einzelnen Prozedur zu generieren, dann wäre dieses Änderungsprotokoll damit nicht in der Unit selber sichtbar (so wie in obigem Beispiel), sondern nur ein Protokollfile oder ein in einem Logviewer dargestellter Text.

Versionskontrollsysteme erleichtern die Arbeit aber doch sehr: wenn eine Kundenänderung sich nicht nur auf eine einzige Stelle bezieht, sondern mehrere Units betroffen sind, muss ich nicht an allen Stellen einzeln dokumentieren, stattdessen wird beim Speichern der Änderung für alle geänderten Dateien der Bezug zum Kundenauftrag einmalig erfasst und ist im CVS Protokoll dann allen Units zugeordnet.

[JasonDX]

Zitat von mjustin:

Ich kenne kein Versionskontrollsystem oder eine CSV-IDE Integration sie so etwas kann oder nur in die Nähe käme.

Alle gängigen Systeme (Git, SVN etc.) arbeiten dateiorientiert. Man kann sich also zu der Unit, in der Procedure Machwas enthalten ist, detailliert auflisten lassen wer wann und warum etwas an der Unit geändert hat. Sich aber nur auf Prozedurebene die Änderungen anzeigen zu lassen, ist mit den mir bekannten Werkzeugen nicht möglich. Müßte man mal recherchieren

die meisten können Diffen, d.h. die Unterschiede zwischen den Änderungen anzeigen. Damit entdeckt man solche Sachen. Natürlich, wenn ein Submit 1200 solcher Änderungen betrifft, wirds schwierig - dann ist das aber die falsche Arbeitsweise.

[hoika]

Hallo,

beim Einchecken der Datei kann man das doch als Info eintragen.
Bei Tortoise-SVN kann ich so viel Text eingeben, wie ich will.
Checke ich genau diese eine Datei als eigene Revision ein,
kann ich bequem danach suchen.


Heiko

[mjustin]

Zitat von Stevie:

In einer Versionsverwaltung wäre das in der Historie. Wenn man den Code liest, interessiert doch nicht mehr, wie oft das mal vor Jahren geblinkt hat und warum.

Änderungen einer einzelnen Prozedur über die Jahre hinweg nachzuvollziehen ist mit einer Versionsverwaltung allerdings schon etwas mühsam. Da man immer nur ein Diff zweier Versionen macht, in dem auch alle anderen Änderungen der Unit enthalten sind. Ein praktisches Feature wäre es schon, die Evolution eines isolierten, definierten Codeabschnitts einer Unit auflisten zu können. Kann das ein aktuelles CVS?

[Bernhard Geyer]

Zitat von bernau:

Der Code ist hier natürlich nur ein Beispiel und natürlich steht nicht in jeder Procedure solch ein Kommentar. Meine Frage war ja, wie es im CSV aussieht? Fällt so etwas sofort in's Auge, oder muss ich eine Aktion durchführen um diese Info's zu lesen. Mir hat es schon oft geholfen, daß ich "zufällig" diese Kommentare gelesen habe.

Wir verwenden die Kombination CVS, Jira und Fisheye.
Man sieht welcher Issue/Fehler welche Quellcodeänderung verursacht hat. Man kann in der History der Änderungen suchen und vieles Mehr...

Dazu brauch ich dann den Quellcode nicht mit Änderungskommentaren verseuchen die nach einiger Zeit das "Man sieht den Wald vor lauter Bäumen nicht mehr"-Problem verursachen.

[mjustin]

Zitat von JasonDX:

Zitat von mjustin:

Ich kenne kein Versionskontrollsystem oder eine CSV-IDE Integration sie so etwas kann oder nur in die Nähe käme.

Alle gängigen Systeme (Git, SVN etc.) arbeiten dateiorientiert. Man kann sich also zu der Unit, in der Procedure Machwas enthalten ist, detailliert auflisten lassen wer wann und warum etwas an der Unit geändert hat. Sich aber nur auf Prozedurebene die Änderungen anzeigen zu lassen, ist mit den mir bekannten Werkzeugen nicht möglich. Müßte man mal recherchieren

die meisten können Diffen, d.h. die Unterschiede zwischen den Änderungen anzeigen. Damit entdeckt man solche Sachen. Natürlich, wenn ein Submit 1200 solcher Änderungen betrifft, wirds schwierig - dann ist das aber die falsche Arbeitsweise.

Ja, nur läßt sich kein mir bekanntes Diff über alle Revisionen auf einen bestimmten Codeabschnitt beschränken. Man müßte dazu alle Unterschiede, die sich nicht auf die interessierende Prozedur beziehen, ausfiltern können.

Ausgabe eines solchen prozedurbezogenen Diff wäre dann (vereinfacht, ohne + und - Marker für neue/gelöschte Zeilen) etwa wie folgt:

Code:

Diff for Procedure ZeigMalWas - Revision 1 to Head

---

Revision 1: 10.10.2012 - E-Mail von Meyer - Will ein Blinken im Sekundentakt.

Procedure ZeigMalWas;
begin
  LassBlinken(1);
end; 

---

Revision 4711: 20.11.2012 - E-Mail von Müller - Blinken zu hektisch. Auf Wunsch nur alle 2 Sekunden.

Procedure ZeigMalWas;
begin  
  LassBlinken(2);
end; 

---

Revision 65332: 20.11.2012 - E-Mail von Müller - Blinken zu hektisch. Auf Wunsch nur alle 2 Sekunden.

Procedure ZeigMalWas;
begin
  LassBlinken(0.5);
end;

[Sherlock]

Zum Thema IDE-Integration: VersionInsight Plus vom Uwe Schuster hat ein "LiveBlame" was in der IDE zu jedem Codeblock anzeigt in welcher Revision der sich geändert hat. Es ist dann ein leichtes sich die Commit-Kommentare dazu anzuschauen.

Sherlock

[vagtler]

Zitat von mjustin:

[...] Ich kenne kein Versionskontrollsystem oder eine CSV-IDE Integration sie so etwas kann oder nur in die Nähe käme. [...]

Sowas möchte ich auch auf keinen Fall im Code haben. Das gehört in das Issue-Management und wird durch Branching und zu den Issues zugeordneten Commits gemanaged.

Die Sachbearbeiter im Issue- und Projekt-Management würden sich bedanken, wenn sie so etwas im Code nachschlagen müssten. Vom Accounting gar nicht erst zu reden... :p

[bernau]

Ich denke es kommt auch auf die Größe des Projekt-Teams an. Wenn es nur zwei Entwickler gibt, dann gibt es kein Projektmanagement.

[p80286]

Interessante Diskussion.
Vor allem, weil die meisten wohl nicht die Probleme haben, die Chemiker angesprochen hat. Wenn man nicht mehr im Thema drin ist oder wenn einem die Entwicklungsoberfläche fehlt (ganz zu schweigen von einem Versionskontrollsystem), dann ist Kommentar im Sourcecode doch sehr hilfreich.

Natürlich muß inc(i) nicht kommentiert werden bei einem

Code:

if boolean(shl(shr(wert,1),1) then

wäre ich mir da nicht so sicher.

Gruß
K-H