Quellcode Kommentieren

[Sir Rufo]

Zitat:

Zitat von Dejan Vu (Beitrag 1267887)

Zitat:

Zitat von p80286 (Beitrag 1267877)

da wird es einem aber auch nicht leicht gemacht, und wenn ich diese EinBustabenAliasse sehe, frag ich mich schon was die Autoren sich dabei denken.

Einerseits, aber das ist das kleinere Übel. Aliase sind ja Abkürzungen, denn sonst könntest Du ja auch den Tabellennamen verwenden. Wenn man eine Nomenklatur hat, sodaß für die Kundentabelle immer der Alias 'kd' oder 'k' verwendet wird, dann geht das schon.

Ich meine eher das Verbergen von kodierter Logik ('Status=3 AND RemovalOptions in (3,4,27)') in Views, SP, UDF etc.

Um ganz korrekt zu sein (Haar-Spalter herauskam) sollte die Nomenklatur die Alias-Bezeichnung für den Kontext regeln.

z.B. die Tabelle Personen kann für Ansprechpartner, Inhaber, etc. verwendet werden und dort sollte der Alias am besten zum verwendeten Kontext passen :)

[p80286]

Zitat:

Zitat von Sir Rufo (Beitrag 1267895)

Um ganz korrekt zu sein (Haar-Spalter herauskam) sollte die Nomenklatur die Alias-Bezeichnung für den Kontext regeln.

z.B. die Tabelle Personen kann für Ansprechpartner, Inhaber, etc. verwendet werden und dort sollte der Alias am besten zum verwendeten Kontext passen :)

Da tippt und tippt man und andere sind wieder schneller:shock:

gruß
K-H

[Dejan Vu]

Zitat:

Zitat von Sir Rufo (Beitrag 1267895)

z.B. die Tabelle Personen kann für Ansprechpartner, Inhaber, etc. verwendet werden und dort sollte der Alias am besten zum verwendeten Kontext passen :)

:thumb: Ich habe Aliase bisher immer als 'Abkürzung' verstanden und verwendet. Aber das heißt ja nicht 'Abbrevation' sondern eben Alias.

Wieder was dazugelernt und das in meinem Alter...

[jfheins]

Zitat:

Zitat von JasonDX (Beitrag 1267617)

Zitat:

Zitat von bernau (Beitrag 1267615)

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:

Zitat von mjustin (Beitrag 1267618)

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" :stupid:

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:

Zitat von jfheins (Beitrag 1268734)

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

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

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

Zitat von p80286 (Beitrag 1268760)

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:

Zitat von Dejan Vu (Beitrag 1268754)

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

Delphi-Quellcode:

unit xyz;

) noch nicht. :wall:

[Dejan Vu]

Zitat:

Zitat von himitsu (Beitrag 1268791)

..aber das CodeFolding funktioniert bei diesem Kommentar (da oben an/über

Delphi-Quellcode:

unit xyz;

) noch nicht. :wall:

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.