Eure besten Quellcode Kommentare...

[himitsu]

Manmal würde ich mir wünschen, wenn es überhaupt Kommentare oder wenigstens eine halbwegs verständliche Hilfe gäbe,
aber wenn man schon tagelang verzweifelt sucht und von einem Problem ins nächste stolpert,
und dann einen Artikel findet, ala "The Worst API Ever Made",
dann vergeht einem auch das letzte Bissl an Lust.

Wenn ich mal was fand und dort standen Kommentare ... dann stimmten sie garnicht.

Und der einzige gut aussehende Code, als Antwort auf eine Frage ....... der bracht mitten drin ab.



https://caseymuratori.com/blog_0025

Hatte die überschrift erst garnicht gesehn und dachte "geil", endlich mal was, das ausführlich aussieht und wirklich um das geht, was ich suche (nicht um irgendwas anderes, mit dem Wort "Trace")

[MaBuSE]

Zitat von himitsu:

Manmal würde ich mir wünschen, wenn es überhaupt Kommentare oder wenigstens eine halbwegs verständliche Hilfe gäbe,

Das kenne ich.

Ich habe auch schon Projekte gesehen, die mehrere Mio Zeilen Quelltext lang sind und per Definition in ca. einer Stunde entstanden sein müssen.
Na ja, bei uns gibt es eine Arbeitsanweisung, dass ca. 10% der Zeit für Dokumentation einzuplanen ist.
Und der/die Entwickler haben sich nicht mal 10 Min Zeit genommen für Doku und Kommentare.

[dummzeuch]

Besser gar keine Kommentare als falsche oder sinnlose ala

Delphi-Quellcode:

// *******************
// * Prozdur bla     *
// *******************
procedure bla;
var
  i: integer; // Schleifenvariable
begin
  // alle Listenelemente durchlaufen
  for i := 0 to Liste.Count -1 do begin
    // Listenelement verarbeiten
    Process(Liste[i]);
  end;
end;

letztere reduzieren die Lesbarkeit ohne irgendwas beizutragen.

Programmierer sollten sich besser auf verständlichen Code (Struktur und Namensgebung) konzentrieren als auf Teufel komm raus Kommentare zu schreiben. Kommentare sollen beschreiben, warum etwas auf eine bestimmte Weise gemacht wird, und das auch nur dann, wenn es nicht offensichtlich ist.

[DeddyH]

[Uwe Raabe]

Zitat von dummzeuch:

Programmierer sollten sich besser auf verständlichen Code (Struktur und Namensgebung) konzentrieren als auf Teufel komm raus Kommentare zu schreiben. Kommentare sollen beschreiben, warum etwas auf eine bestimmte Weise gemacht wird, und das auch nur dann, wenn es nicht offensichtlich ist.

Zitat von Brian W Kernighan and P. J. Plaugher:

Don't comment bad code - rewrite it.

[himitsu]

Dein Beispiel klingt wie die Hilfe einer gewissen Firma.

Zitat:

Ohh, ein neues Property, mit unverständlichem Namen
...

[F1]
mal gucken was das machen soll

Zitat von OH:

Das ist Property Abc in Klasse Xyz der unit Qrs.

UND WAS MACHT DAS NUN?

Genauso wie "oh, komischer Prozess" im Taskmanager .... fragen wir mal G/Y/B/... und die Top10 Suchergebnisse sagen alle

Zitat:

das ist Abc.exe soundsogroß in Verzeichnis hierundda der Firma "NameAusVersionsresource"

UND WAS MACHT DIE NUN?

Das ALLES wusste man auch vorher schon.



Es gibt in Firmen teilweise vorschriften, wonach x% des Quellcodes Kommentare sein müssen.

Da kommt dann auch oft sowas bei raus.

[MaBuSE]

Zitat von himitsu:

Es gibt in Firmen teilweise vorschriften, wonach x% des Quellcodes Kommentare sein müssen.
Da kommt dann auch oft sowas bei raus.

In Deiner Brust scheinen 2 Herzen zu schlagen

Einerseits schreibst Du, dass wenn Firmen den Entwicklern vorschreiben, sie möchten bitte dokumentieren (Quellcode, Handbücher, Readme, ...), oft nur Müll rauskommt.

Zitat von himitsu:

Manmal würde ich mir wünschen, wenn es überhaupt Kommentare oder wenigstens eine halbwegs verständliche Hilfe gäbe,
aber wenn man schon tagelang verzweifelt sucht und von einem Problem ins nächste stolpert,...

Andererseits möchtest Du in Quellcode Kommentare und "wenigstens eine halbwegs verständliche Hilfe" haben.

Zitat von MaBuSE:

Ich habe auch schon Projekte gesehen, die mehrere Mio Zeilen Quelltext lang sind und per Definition in ca. einer Stunde entstanden sein müssen.
Na ja, bei uns gibt es eine Arbeitsanweisung, dass ca. 10% der Zeit für Dokumentation einzuplanen ist.
Und der/die Entwickler haben sich nicht mal 10 Min Zeit genommen für Doku und Kommentare.

Bei uns gibt es die Richtlinie, dass in der Zeitschätzung ca. 10 % für Dokumentation vorzusehen sind.
Das beinhaltet Quellcode Kommentare, Readme Dateien, Installations-Anweisungen, Benutzerbücher, ...

Der Entwickler nutzt die 10% aber lieber als Puffer um seine Arbeit fristgerecht abzuschließen. Doku ist ja nicht wichtig.

[himitsu]

Das Beispiel aus #514, hatten wir hier öfters mal.

Grade in dem was man in einigen Schulen lernen soll, da war wirklich jede einzelne Zeile kommentiert, was da gemacht wird, auch wenn 95% davon der Quellcode selber gesagt hat nd weitere 4%, wenn man ordentliche Namen für Variablen/Funktionen benutzt hätte.
Nur die eine Zeile, die jemand nicht verstand, weil es dem Code nicht richtig anzusehn ist, was ermacht, das war Die ohne Kommentar.



Kommentare nur um des Kommentares Willen, ohne dass er einen Mehrwert bringt, außer den Code zwischen sich untergehen zu lassen ... nja

[Maliko]

Zitat von dummzeuch:

Besser gar keine Kommentare als falsche oder sinnlose ala

Delphi-Quellcode:

// *******************
// * Prozdur bla     *
// *******************
procedure bla;
var
  i: integer; // Schleifenvariable
begin
  // alle Listenelemente durchlaufen
  for i := 0 to Liste.Count -1 do begin
    // Listenelement verarbeiten
    Process(Liste[i]);
  end;
end;

Leider gibt es immer wieder Firmen die genau sowas wollen. Ich war mal in einer Firma, da sah der Quellcode genauso aus, weil der Entwicklungsleiter darauf bestanden hat, dass jede einzelne Zeile Code kommentiert werden muss. Da kommt dann so ein Müll bei raus. Manchmal habe ich fürs Kommentieren länger gebraucht als für das Schreiben der Funktion.

[MaBuSE]

Zitat von Maliko:

Zitat von dummzeuch:

Besser gar keine Kommentare als falsche oder sinnlose ala

Delphi-Quellcode:

// *******************
// * Prozdur bla     *
// *******************
procedure bla;
var
  i: integer; // Schleifenvariable
begin
  // alle Listenelemente durchlaufen
  for i := 0 to Liste.Count -1 do begin
    // Listenelement verarbeiten
    Process(Liste[i]);
  end;
end;

Leider gibt es immer wieder Firmen die genau sowas wollen. Ich war mal in einer Firma, da sah der Quellcode genauso aus, weil der Entwicklungsleiter darauf bestanden hat, dass jede einzelne Zeile Code kommentiert werden muss. Da kommt dann so ein Müll bei raus. Manchmal habe ich fürs Kommentieren länger gebraucht als für das Schreiben der Funktion.

Dann hätte ich das so gemacht

Delphi-Quellcode:

// *******************
// * Prozdur blub    *
// *******************
procedure bla;
var
  i: integer; // j
begin
  // for j := 0 to MeineListe.Count -1 do begin
  for j := 0 to MeineListe.Count -1 do begin
    // Process(MeineListe[j]);
    Process(Liste[i]);
  end;
end;

da wäre die Verwirrung perfekt
oder besser so:

Delphi-Quellcode:

// 
procedure bla;
var
  i: integer; // 
begin
  // 
  for i := 0 to Liste.Count -1 do begin
    // 
    Process(Liste[i]);
  end;
end;

Dann ausdrucken und offline kommentieren.