Quellcode Kommentieren

[bernau]

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. Wenn du überall dieses Vorgehen hast, möcht ich nicht deinen Code lesen, denn der würde wahrscheinlich zu 99% aus altem auskommentierten Code bestehen.

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.

[JasonDX]

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.

Dazu muss eine Aktion durchgeführt werden. Hat auch seinen Grund, da zu 99% der Zeit diese Information nicht sinnvoll/hilfreich und damit platzraubend ergo kontraproduktiv wäre.
Diese Information als Kommentare in den Code zu setzen ist nur in wenigen Ausnahmen sinnvoll, und entsprechend spärlich sollten diese Kommentare verwendet werden.

[jfheins]

Zitat von JasonDX:

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.

Dazu muss eine Aktion durchgeführt werden. Hat auch seinen Grund, da zu 99% der Zeit diese Information nicht sinnvoll/hilfreich und damit platzraubend ergo kontraproduktiv wäre.
Diese Information als Kommentare in den Code zu setzen ist nur in wenigen Ausnahmen sinnvoll, und entsprechend spärlich sollten diese Kommentare verwendet werden.

Zitat von mjustin:

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

Dazu kann ich gerade mal einen kleinen Kommentar abgeben: Codelens in VS unterstützt nun auch git, das sieht dann im Code so aus:
http://blogs.msdn.com/b/visualstudio...-update-3.aspx
Die Änderungen beziehen sich dann tatsächlich nur auf die Prozedur/Klasse über der dieser Hinweis ist. Man kann dann die commit-Details aufrufen und aus diesen dann wiederum auf ein Datei-Diff zugreifen.

Damit das wirklich weiterhilft, sollte man natürlich kleine Änderungen mit aussagekräftigen Nachrichten machen. Es hilft nichts, wenn man sieht die Prozedur wurde 3 Mal geändert, und die Nachrichten sind "Diverses", "." und "Zeug"

Ich muss jetzt erstmal schauen, wie sinnvoll/praktisch das ganze ist. Zu Kommentaren im Allgemeinen kann ich übrigens noch folgendes Schmuckstück beitragen:

Code:

// Vorsteuerung: 3000 upm entsprechen 10 m/s ==> Faktor 0,3   
   int16_t Vorsteuerung = upm_value / 2; // Faktor 0,25

[himitsu]

Zitat von jfheins:

Zu Kommentaren im Allgemeinen kann ich übrigens noch folgendes Schmuckstück beitragen:

Meinst du das 0,3 ... 0,25 ... oder doch eher 0,5 ?

[Dejan Vu]

Das ganze Kommentieren?Ja?Nein?Wann?Wieoft? Gedöns hat ja folgenden Hintergrund:
Als Entwickler ist man (wenn man nicht gerade Code produziert) den lieben langen Tag damit beschäftigt, Code zu verstehen. Implementierungsdetails unterhalb des aktuellen Abstraktionsniveaus sind hier hinderlich: Hier mal zwei Beispiele, die genau das gleiche machen:

Delphi-Quellcode:

if not Customers.FindById(customer.ID) then
  Customers.CreateNew(customer);

Delphi-Quellcode:

var
  searchRec : TCustomerSearchRec;
  idFilter : TSearchFilterCriteria;
  newCustomer : TCustomerEntity;

begin
// search the customer by creating a customer search record
  searchRec := TCustomerSearchRec.Create;
// this is the new search filter criteria! really cool stuff. Check it

  idFilter := TSearchFilterCriteria.Create;
// 2013-03-04: JFuddle: [CodeImp] replaced constant field names by definition
// 2013-07-12: MPeck: Yeah, but replace with the correct one, you moron. :-)
  idFilter.Field := Customers.DataDescription.Fieldnames.ID;
  idFilter.Condition := fcoEqual;
  idFilter.Value = customer.ID;

  searchRec.Filter.Add(idFilter);
// now try to find it
  if not Customers.Find(searchRec) then begin
// nope, not found, create a new one
     newCustomer := Customers.CreateEntity;
     newCustomer.Id := customer.Id;
     newCustomer.Name := customer.Name;
     ....
     Customers.Post(newCustomer);
  end;

Das erste versteht man sofort und intuitiv, beim zweiten muss man schon lesen. Klar ist das ordentlich, aber WTF, wen interessieren Details und/oder Kommentare? Wenn ich wissen will, wie neuerdings gesucht wird, gehe ich in die 'Find' Methode rein. Das kostet mich einen Click. Und wenn ich will, wie genau ein neuer Kunde angelegt wird auch.

Wir machen dieses Form des Codelesens 100 mal am Tag. Wenn ich mich jedesmal durch Kommentar und Codearien lesen muss, um das zu verstehen (hier geht das ja noch), dann bin ich genervt, gestresst und viel unproduktiver, als wenn ich mich durch sauberen Code lese, der minimal kommentiert, selbsterklärend und klar strukturiert ist. Ich schaffe mehr, bin produktiver und einfach besser drauf.

Wenn ich kein CVS habe, oder ich unbedingt Revisionsinformationen und codechange-Kommentare im Code vorhalten will, dann benötige ich etwas zum Verbergen (codefolding, regions in der Art) dieser fast immer unnützen Information.

@jfheins: Genau deshalb sagt man ja, das Kommentare (irgendwann anfanfangen zu) lügen oder einfach Mist erzählen.

[p80286]

Nun einiges von Deinen Kommentarbeispielen würde bei mir unter "Geschwafel" einsortiert, und dafür ist mir meine Zeit wirklich zu schade.

@jfheins:
Da hätten wir einen Grund mal nachzufragen was denn nun eigentlich richtig ist, der Programmierer/Kommentator wußte dies augenscheinlich nicht.

Gruß
K-H

[Dejan Vu]

Zitat von p80286:

Nun einiges von Deinen Kommentarbeispielen würde bei mir unter "Geschwafel" einsortiert, und dafür ist mir meine Zeit wirklich zu schade.

Genau. Deshalb plädiere ich ja dafür, das alles wegzulassen. Von den o.g. Kommentaren braucht man imho keinen Einzigen, auch nicht die Historie.

[himitsu]

Zitat von Dejan Vu:

Wenn ich kein CVS habe, oder ich unbedingt Revisionsinformationen und codechange-Kommentare im Code vorhalten will, dann benötige ich etwas zum Verbergen (codefolding, regions in der Art) dieser fast immer unnützen Information.

Ich hatte jetzt mal versucht sowas in die Unit-Dokumentation aufzunehmen, was eigentlich recht einfach geht.
Es gibt nur ein winziges Problem.

Man kann eine Unit dokumentieren (DocInsight), aber das CodeFolding funktioniert bei diesem Kommentar (da oben an/über unit xyz; ) noch nicht.

[Dejan Vu]

Zitat von himitsu:

..aber das CodeFolding funktioniert bei diesem Kommentar (da oben an/über unit xyz; ) noch nicht.

Das ist ja bescheuert. Und unter der 'Unit' Deklaration gehts nicht?

[himitsu]

Die Dokumentation gehört vor/über das zu dokumentierende Objekte und nicht dahinter.
(wobei ich es mit bei Property, Kostante und Co. auch gern mal dahinter gewünscht hätte stupid)

Das Erste "in" jeder Unit, also der Uses-Abschnitt, lässt sich nicht dokumentieren und bei Compiler-Optionen geht es natürlich auch nicht.