Quellcode Kommentieren

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