Forum: PC-Programmierung C Kommentierung in der Praxis


Announcement: there is an English version of this forum on EmbDev.net. Posts you create there will be displayed on Mikrocontroller.net and EmbDev.net.
von Lars Ding. (Gast)


Lesenswert?

Hallo,

da hab ich direkt die nächste Frage...

wir haben in Programmierung I und II in der Uni immer mit Java 
gearbeitet. Quellcode musste immer ausreichend kommentiert werden , dank 
Jdoc war das auch immer einheitlich etc. pp.

Wie sieht eine richtige Kommentierung in C aus? Kommentiert man 
detalliert vor jeder Funktion, was zurückgegeben wird? Wie sieht das im 
Berufsalltag aus?

Ich bedanke mich

Lg

von Joachim D. (Firma: JDCC) (scheppertreiber)


Lesenswert?

Der Könner knäult alles in eine Zeile. Kommentare sind etwas
für Mädchen ;)

Es gibt Konventionen, halt unverbindlich. Kommentierungen sind
da sinnvoll wo es etwas nicht selbsterklärendes gibt oder Änderungen
auf "Kundenwunsch" notwendig waren. Man sollte da für sich einen
Mittelweg finden (Kommentare wo notwendig, halt nicht überladen).

von Samuel H. (musicsammy)


Lesenswert?

"The Exceptional Beauty of Doom 3’s Source Code":
http://kotaku.com/5975610/the-exceptional-beauty-of-doom-3s-source-code

von Sven P. (Gast)


Lesenswert?

Lars Ding. schrieb:
> Quellcode musste immer ausreichend kommentiert werden , dank
> Jdoc war das auch immer einheitlich etc. pp.
Allein dafür sollte man den Professor mal steinigen... seufz

von Mark B. (markbrandis)


Lesenswert?

Sven P. schrieb:
> Lars Ding. schrieb:
>> Quellcode musste immer ausreichend kommentiert werden , dank
>> Jdoc war das auch immer einheitlich etc. pp.
> Allein dafür sollte man den Professor mal steinigen... *seufz*

Was ist daran falsch?

Ich habe selten im Leben ein Zuviel an Kommentarzeilen gelesen,
oft genug jedoch waren es zu wenige.

von Lars Ding. (Gast)


Lesenswert?

Sven P. schrieb:
> Lars Ding. schrieb:
>> Quellcode musste immer ausreichend kommentiert werden , dank
>> Jdoc war das auch immer einheitlich etc. pp.
> Allein dafür sollte man den Professor mal steinigen... seufz

Warum?^^

von Sven P. (Gast)


Lesenswert?

Mark Brandis schrieb:
> Sven P. schrieb:
>> Lars Ding. schrieb:
>>> Quellcode musste immer ausreichend kommentiert werden , dank
>>> Jdoc war das auch immer einheitlich etc. pp.
>> Allein dafür sollte man den Professor mal steinigen... *seufz*
>
> Was ist daran falsch?

Das 'muss' ist falsch. Kommentieren müssen ist mindestens genauso 
bescheuert wie garnicht zu kommentieren. Wobei garnicht kommentierte 
Quelltexte dann meistens noch weniger Fragen offen lassen, als solche, 
die kommentiert werden mussten.

von Thomas B. (escamoteur)


Lesenswert?

Beschreibe in Kommmentaren nichts was man nicht auch aus dem Code lesen 
kann. Oft ist es besser lange sprechende Variablen- und Funktionsnamen, 
als jede Zeile zu kommentieren. Kommentare sollten vor allen den Blick 
aufs ganze erleichtern und nicht die Funktion einzelner Zeilen 
beschreiben. Ein Problem ist nämlich, dass oft der Code verändert wird, 
der alte Kommentar jedoch stehen bleibt und dann nicht mehr 
zusammenpasst.

Daher eher sparsam und versuchen den Code so zu gestalten, dass er 
leicht lesbar ist.

von Sven B. (scummos)


Lesenswert?

Viele Projekte halten sich an Doxygen [1], das ist auf jeden Fall eine 
gute Methode, Code zu kommentieren, wenn man die Absicht hat, aus den 
Kommtenaren eine API-Referenz zu generieren. Wen man nur erklären will, 
was der Algorithmus tut, den man gerade baut, dann einfach Kommentare 
mit // einleiten, gleich einrücken wie die umliegenden Code-Zeilen, und 
Kommentare nicht mit Code in eine Zeile schreiben.

Grüße,
Sven

___
[1] Code commentieren für Doxygen: 
http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html

von Karl H. (kbuchegg) (Moderator)


Lesenswert?

Samuel Hildebrandt schrieb:
> "The Exceptional Beauty of Doom 3’s Source Code":
> http://kotaku.com/5975610/the-exceptional-beauty-of-doom-3s-source-code

Interessanter Artikel.
Auch wenn ich nicht mit allem konform gehe, das meiste deckt sich mit 
meinen Ansichten, wie Code aussehen sollte.
Insbesondere die 3 Regeln der Kommentierung bringen es auf den Punkt
1
* Code should be locally coherent and single-functioned: One function
2
  should do exactly one thing. It should be clear about what it's doing.
3
4
* Local code should explain, or at least hint at the overall system
5
  design.
6
7
* Code should be self-documenting. Comments should be avoided whenever
8
  possible. Comments duplicate work when both writing and reading code.
9
  If you need to comment something to make it understandable it should
10
  probably be rewritten.

Kommentiere nicht das wie sondern das warum. Wenn immer möglich, forme 
den Code so um, dass sich das warum aus dem Code selber ergibt.

Ein
   Nettopreis = Bruttopreis - Steuer;
muss man nicht kommentieren. Es ist im Code offensichtlich, was hier 
gerechnet wird.

von Sven B. (scummos)


Lesenswert?

Beim Kommentieren von Bibliotheken geht es ja nicht großteils darum, den 
Algorithmus zu erklären, sondern die API. Natürlich sollte eine API auch 
ein gewisses Stück weit selbsterklärend, sein, und die API einer 
Vektor-Klasse ist das sicherlich auch. Für andere Dinge braucht man aber 
sicherlich Dokumentation, und die Docstrings über den Funktionen im 
Header-File sind ein guter Ort dafür.

Grüße,
Sven

von Karl H. (kbuchegg) (Moderator)


Lesenswert?

Zweifellos.

Aber die Professoren Doktrin (ist ja nicht nur bei ihm so), des 'alles 
muss kommentiert werden', führt dann oft zu seltsamen Blüten wie
1
   int i;    // Schleifenzaehler i

oder
1
///   jetzt werden alle Variablen definiert
2
  int  i; // Schleifenzaehler i
3
  int  k; // k ist die Anzahl der gleichen Bruttopreise in der Datenbank
4
5
// Funktionsabschnitt, hier stehen die Funktionen
6
7
// Diese Funktion berechnet die Anzahl der Datensaetze
8
void berHugo1( void )
9
{
10
  k = .....   // jetzt wird k berechnet
11
}

und zwar OHNE dass besagter Professor dagegen etwas einzuwenden hätte. 
Dem genügt es, wenn da ein Kommentar steht. Möglichst in jeder Zeile. 
Was anderes interessiert ihn nicht. Und wehe eine Zeile ist nicht 
kommentiert. Dann gibt es Punkteabzüge.

von Sven B. (scummos)


Lesenswert?

Ja, das ist natürlich völliger Quatsch. ;)

von BC (Gast)


Lesenswert?

Lars Ding. schrieb:
> wir haben in Programmierung I und II in der Uni immer mit Java
> gearbeitet. Quellcode musste immer ausreichend kommentiert werden , dank
> Jdoc war das auch immer einheitlich etc. pp.

Für C (und andere Sprachen) kann ich doxygen dringend empfehlen.

> Wie sieht eine richtige Kommentierung in C aus? Kommentiert man
> detalliert vor jeder Funktion, was zurückgegeben wird? Wie sieht das im
> Berufsalltag aus?

In meinem Berufsalltag werden alle Funktionen, Strukturen, globale 
Variablen und in sinnvollen Fällen auch C-Dateien mit doxygen 
Kommentaren versehen.

Innerhalb von Funktionen nach Gespür. Ich kommentiere etwas mehr, andere 
etwas weniger. Hängt auch davon ab, wie komplex die Materie ist und wie 
lange der Code eingesetzt und gewartet werden soll.

Karl Heinz Buchegger schrieb:
> Aber die Professoren Doktrin (ist ja nicht nur bei ihm so), des 'alles
> muss kommentiert werden', führt dann oft zu seltsamen Blüten wie
>    int i;    // Schleifenzaehler i

Naja, diese Beispiele aus der Uni zeigen eher, die Professoren 
verzweifelt zu erreichen versuchen, daß die Studenten ihren Code 
verstehen und erklären können.

Wenn ich frage, was dieses Konstrukt soll, möchte ich hören, daß es sich 
um die Deklaration einer lokalen Variable handelt, welche in der später 
folgenden for-Schleife als Schleifenzähler verwendet wird. Ein "ja, das 
Ding brauch' ich da unten" reicht halt leider nicht.

von Thomas H. (flaretom)


Lesenswert?

Hallo,

Die beste Kommentierung erreicht man, wenn man sie gar nicht benötigt. 
Also Variablen und Funktionen/Methoden über die Namen sich selbst 
erklären lassen.
Stichwort Refractoring:
Die Methoden sind so klein, dass sie nur eine kleine Aufgabe übernehmen, 
die über den Methodennamen klar wird. Die übergeordneten Methoden 
bestehen  dadurch aus Aufrufen, die sich selbst erklären.
http://sourcemaking.com/refactoring/extract-method

Blöderweise gibt es Metriken (MISRA), die einen bestimmten Anteil 
Kommentar verlangen, sonst gibt es vom Software-Qualitäter Haue ;).

Beste Grüße, Tom

von Mark B. (markbrandis)


Lesenswert?

Karl Heinz Buchegger schrieb:
> und zwar OHNE dass besagter Professor dagegen etwas einzuwenden hätte.
> Dem genügt es, wenn da ein Kommentar steht. Möglichst in jeder Zeile.

Ich gebe Dir ja soweit Recht, niemand will dass alle Zeilen kommentiert 
werden.

Aber was kommt denn in der beruflichen Praxis öfter vor:
1.) Code mit einem erheblichen Zuviel an Kommentaren
2.) Code mit sehr wenig bis gar keinen Kommentaren, und die Variablen- 
und Funktionsnamen sind auch nicht gerade selbsterklärend, bisweilen gar 
eher verwirrend.

Meiner Erfahrung nach ist 2.) der weitaus häufigere Fall, und das mit 
Abstand.

von Karl H. (kbuchegg) (Moderator)


Lesenswert?

Mark Brandis schrieb:
> Karl Heinz Buchegger schrieb:
>> und zwar OHNE dass besagter Professor dagegen etwas einzuwenden hätte.
>> Dem genügt es, wenn da ein Kommentar steht. Möglichst in jeder Zeile.
>
> Ich gebe Dir ja soweit Recht, niemand will dass alle Zeilen kommentiert
> werden.
>
> Aber was kommt denn in der beruflichen Praxis öfter vor:
> 1.) Code mit einem erheblichen Zuviel an Kommentaren
> 2.) Code mit sehr wenig bis gar keinen Kommentaren, und die Variablen-
> und Funktionsnamen sind auch nicht gerade selbsterklärend, bisweilen gar
> eher verwirrend.
>
> Meiner Erfahrung nach ist 2.) der weitaus häufigere Fall, und das mit
> Abstand.


Du hast 3) vergessen

3) Die Variablen- und Funktionsnamen sind nicht gerade selbsterklärend, 
und die Kommentare sind nichtssagend und bisweilen sogar falsch.

Und genau das ist es, was unsere lieben Universitäten oft als 
Studienabgänger produzieren.

Ich hab ja grundsätzlich kein Problem damit, wenn Kommentierung 
gefordert wird. Sinnvolle Kommentierung! Aber genau das 'sinnvoll' 
bleibt halt so oft auf der Strecke.

Beispiel:  (ok, bischen überspitzt)
Bei meinem Professor im ersten Studienjahr ("Einführung in die 
Programmierung". Arbeitssprache PL/1, Prof. Schulz, Uni Linz, 1982) wäre 
ich mit einem
1
     nrWordsFound++;
niemals durchgekommen. Jede Anweisung war zu kommentieren. Wenn da stand
1
     iy0ab++;      // iy0ab inkrementieren
dann war dem Genüge getan und alles war ok. Wirklich alles. Das 'iy0ab' 
störte ihn nicht weiter, Hauptsache der Kommentar war vorhanden.

Und gegen derartige Kommentierforderungen wehre ich mich. Das ist 
sinnlos. Wenn man möchte, dann soll er von mir aus schreiben
1
     nrWordsFound++;     // festhalten, dass damit ein passendes Wort
2
                         // mehr gefunden wurde
Ist ok für mich, damit hab ich kein Problem. Aber notwendig wäre es 
meiner Meinung nach nicht. Der Code spricht für sich selber.

von asmhobbyist (Gast)


Lesenswert?

Ich denke, generell ist mehr besser als weniger, denn man übt sich ja 
auch im Kommentieren.

Erfahrungsgemäß kommentieren stärkere Programmierer hilfreicher als 
schwächere. (Was hieße, besser programmieren -> besser kommentieren)
(üben üben...)(Rockstarprogrammer werden: täglich entwickeln)
(Auch tieferes Verständnis und Erfahrung hilft, entscheidende Stellen 
herauszuarbeiten)

Lehrbücher sind eine ganz gute Orientierung (K+R z.B.) oder 
wissenschaftliche Artikel.

Auch die Perspektive des Codelesers nicht vergessen. Da viele Leute vor 
Assembler weglaufen (nur als Beispiel) ist vielleicht nicht immer klar,
was xor rax,rax heißt oder mov bp,sp usw. geschweige denn, wo der 
Knackpunkt eines Algorithmus versteckt sein mag.

Es ist sicher auch hilfreich, ein Fehlerprotokoll + 
Schwierigkeitenprotokoll zu machen.

Und nicht zuletzt hilft die Auseinandersetztung damit, wie ich 
dokumentiere, was ich zusammencode - besser zu verstehen, was man 
eigentlich macht (z.B. "Diesen Teil habe ich zusammengeklaut, keine 
Ahnung, was hier vor sich geht").

(Man kann bei K+R auch gut sehen, wie der Code selber und 
Kommentiernotwendigkeit zusammenhängen.
Wenn die z.B schreiben
1
int lower, upper, step;
dann wirkt das schon ganz schön pragmatisch.
1
char coal;
eher nicht so.)

von der mechatroniker (Gast)


Lesenswert?

> Auch die Perspektive des Codelesers nicht vergessen. Da viele Leute vor
> Assembler weglaufen (nur als Beispiel) ist vielleicht nicht immer klar,
> was xor rax,rax heißt oder mov bp,sp usw.

Ich kommentiere aber immer für einen imaginären Leser meines Quellcodes, 
der wenigstens die betreffende Programmiersprache beherrscht. Alles 
andere ist sinnlos und resultiert eben in Dingen wie
1
i++;  // i um 1 erhöhen

von asmhobbyist (Gast)


Lesenswert?

der mechatroniker schrieb:
> Ich kommentiere aber immer für einen imaginären Leser meines Quellcodes,
> der wenigstens die betreffende Programmiersprache beherrscht. Alles
> andere ist sinnlos und resultiert eben in Dingen wie
>
1
i++;  // i um 1 erhöhen

Ich muß gestehen, ich kommentiere auch für mich selber. ;)

In einem Mileu von Anfängerfragen und je nach Frage wäre ein
1
i++; // i = i + 1
oder
1
i++; // dec cx

so sinnlos nicht.
Es kommt halt auf den Zusammenhang an.

(und wenn sowieso alle nur schrieben var++ oder ähnlich, könnte man auch 
bei cx bleiben (gäbe es nicht auch noch andere Hardwarestrukturen)).

(oder andere Programmiersprachen und Programmierer, und Codierstile):
1
let mysinwave = map sin [1..32]
Gibt es eine Ahnung, was dieser Code bzw. diese Funktion (kein c !) 
macht?

Letztlich kann man noch fragen:
Wieso Kommentare zum Code scheiben, wenn der Leser die 
Programmiersprache(und den Code) beherrscht?

von der mechatroniker (Gast)


Lesenswert?

> Letztlich kann man noch fragen:
> Wieso Kommentare zum Code scheiben, wenn der Leser die
> Programmiersprache(und den Code) beherrscht?

Weil der Leser (das kann ich selbst sein, wenn ich zwei Jahre später 
draufschaue) mein Programm (!) nicht kennt.

von Jan K. (schwarz-brot)


Lesenswert?

Im Projektfach meines Studiums wurde ein kleiner Roboter entwickelt und 
via µControler gesteuert. Der betreuende Prof war reiner Maschinenbauer 
und hatte von Software kaum Ahnung. Diese Konstellation ist zwar eher 
unüblich und hatte besondere Hintergründe - allerdings war es eine 
interessante Erfahrung, den Quelltext so aufzubereiten, dass der Prof 
daraus ersehen konnte, was passiert. Hier war ganz klar die besondere 
Forderung, extrem selbsterklärenden Code zu schreiben und zielgerichtet 
zu kommentieren, schließlich hing ein großer Teil der Endnote davon ab. 
Er hat sich regelmäßig auf den aktuellen Stand bringen lassen und alles, 
was ihm nicht auf Anhieb klar wurde, hinterfragt.

Jeder von uns hat dadurch viel mitgenommen, was die Sinnhaftigkeit von 
Kommentaren und selbsterklärendem Code angeht. Ich kann nur empfehlen, 
so zu kommentieren, als würde man für einen unvorbelasteten Leser 
erklären. Das hat nicht zuletzt bei den abschließenden Präsentationen 
und bei Rückfragen vieles erleichtert.

von Joachim D. (Firma: JDCC) (scheppertreiber)


Lesenswert?

Jan K. schrieb:
> Jeder von uns hat dadurch viel mitgenommen, was die Sinnhaftigkeit von
> Kommentaren und selbsterklärendem Code angeht. Ich kann nur empfehlen,
> so zu kommentieren, als würde man für einen unvorbelasteten Leser
> erklären. Das hat nicht zuletzt bei den abschließenden Präsentationen
> und bei Rückfragen vieles erleichtert.

Schön und gut.

Man sollte trotzdem nicht in epischer Breite ein i++ erklären
müssen. Für so etwas gibt es Computerbücher.

von Jan K. (schwarz-brot)


Lesenswert?

Joachim Drechsel schrieb:

> Schön und gut.
>
> Man sollte trotzdem nicht in epischer Breite ein i++ erklären
> müssen. Für so etwas gibt es Computerbücher.


Ja, richtig.
Man könnte es alternativ aber auch klassisch als i=i+1 hinschreiben. 
Hätte jeder sofort verstanden. Allerdings stimme ich Dir völlig zu - 
Banalitäten muss man nicht in epischer Breite darlegen. Und wenn beim 
Leser kein Interesse da ist, die Materie zu verstehen, hilft auch der 
beste Kommentar nix.

von Joachim D. (Firma: JDCC) (scheppertreiber)


Lesenswert?

Ich habe schon mehrere Computerbücher übersetzt bzw neu verfaßt
(bei Vieweg, dBASE etc). Da kann ich mich mit Kommentaren austoben
und dem Leser das genau erklären - da macht das auch Sinn.

Aber nicht in einem Quellcode der nicht für Sachfremde bestimmt ist.

von Mark B. (markbrandis)


Lesenswert?

Joachim Drechsel schrieb:
> Aber nicht in einem Quellcode der nicht für Sachfremde bestimmt ist.

Und was für ein Quellcode soll das sein?

Schließlich gibt es in jeder Firma Neueinsteiger (ob nun mit 
Berufserfahrung oder ohne), die mit dem bestehenden Code zurechtkommen 
müssen.

von Sven P. (Gast)


Lesenswert?

Jan K. schrieb:
> Ja, richtig.
> Man könnte es alternativ aber auch klassisch als i=i+1 hinschreiben.
Man könnte alternativ auch BASIC oder Cobol schreiben, das hätte auch 
jeder(...) verstanden.

Es ist nicht Aufgabe der Kommentierung, einem fachfremden Leser die 
Programmiersprache zu erklären. Noch viel weniger ist es zweckdienlich, 
Programme so zu formulieren, dass jemand sie versteht, der die 
Programmiersprache überhaupt nicht beherrscht.

Natürlich sollen Kommentare zum Verständnis beitragen. Aber wenn der 
Lesen ein Problem mit 'i++' oder ähnlichen Banalitäten hat, dann sollte 
er vielleicht erst einmal ein paar Grundlagen zur Sprache lernen, oder?

von Johann L. (gjlayde) Benutzerseite


Lesenswert?

Jan K. schrieb:
> Joachim Drechsel schrieb:
>
>> Schön und gut.
>>
>> Man sollte trotzdem nicht in epischer Breite ein i++ erklären
>> müssen. Für so etwas gibt es Computerbücher.
>
>
> Ja, richtig.
> Man könnte es alternativ aber auch klassisch als i=i+1 hinschreiben.

Das ist nicht der Punkt.  Kommentare wie
1
// Includiert stdio.h
2
#include <stdio.h>
3
4
// Addiere 1 zu i
5
i = i + 1
6
7
// Funktionsaufruf
8
func();

sind kompletter Fubbes und verstellen den Blick aufs Wesentliche:

- Warum wird i erhöht?
- Wird es überhaupt erhöht oder kommt es evtl. zu einem Überlauf?
- Was ist im Falle des Überlaufs?
  - Inspezifiziert? (Siehe API-Dokumentation)
  - Kann nie vorkommen, weil: ...
  - etc.

Hier ein Beispiel aus der Praxis (eine Wurzelberechnung in asm):
1
    mul     Q1, Q1    ; Quadriere Q1
2
    sub     A1, R0    ; Subtrahiere R[] << 8 von A[]
3
    sbc     A2, R1
4
    clr     A0        ; Setze A[0] auf 0

Was würden solche Kommentare zur Erhellung beitragen ? Absolut nichts!

Hier der richtigen Kommentare:
1
    ;; Set up A according to Invariance
2
    ;;
3
    ;;     X * 2^n  =  A + Q'^2 / 2^{16-n}
4
    ;;
5
    ;; Where  Q' = Q - Q mod 2  and we take all values as 16-bit integers.
6
    ;; Notive that Q is even except in the last step with n = 16.  Now we
7
    ;; have n = 8 and therefore  Q' = Q.
8
9
    mul     Q1, Q1
10
    sub     A1, R0
11
    sbc     A2, R1
12
    clr     A0

Im ersten Kommentar versteht man nur scheinbar was passiert aber nicht 
wirklich was das soll.

Im zweiten Fall ist zumindest klar, daß evtl. Hirnschmalz notwendig ist, 
um tiefer in den Algorithmus einzusteigen und welche Rolle die 
Codesequenz im Gesamtbild des Algorithmus' hat.

von asmhobbyist (Gast)


Lesenswert?

Johann L. schrieb:

> Das ist nicht der Punkt.  Kommentare wie...

So hatte Jan das oben auch nicht gemeint. Eher so:
1
for(zaehler=MIN; zaehler<=MAX; zaehler=zaehler +1){
Ich fand noch weiter oben den Hinweis von Joachim Drechsel darauf, einen 
(seinen) Mittelweg zu finden gut. Knuth selbst hatte sich auch Gedanken 
gemacht und fand einen (seinen) Mittelweg zwischen Readmefile und 
Sourcecode:
http://www-cs-faculty.stanford.edu/~knuth/cweb.html

von MaWin (Gast)


Lesenswert?

Man kommentiert nur das, was durch dem Quelltext nicht bereits 
dokumentiert ist. Hast du also Funktionen und Variablen gut definiert, 
sparst du Kommentare gegenüber jemandem der grlb als Funktionsname und 
i_1a als Variablenname verwendet.
Im Header kann man auch mal jede Interface-Funktion in Prosa erklären 
und was das Modul überhaupt macht. Im Programmcode dokumentiert man 
mögliche Probleme (geht nicht mit negativen Werten) Erweiterungen 
(malloc Rückgabe besser prüfen) und Fehlerbearbeitungsstellen.

von der mechatroniker (Gast)


Lesenswert?

1
for(zaehler=MIN; zaehler<=MAX; zaehler=zaehler +1){

Und was ist damit gewonnen gegenüber einem
1
for(zaehler=MIN; zaehler<=MAX; zaehler++){

Letzteres entspricht nämlich dem ganz normalen for-Schleifen-Idiom, was 
man tausendmal in C-Sourcecode findet. An ersterem bleibt man beim Lesen 
einen kurzen Augenblick "hängen", um dann festzustellen, dass semantisch 
doch nichts ungewöhnlich ist. Macht den Code nicht lesbarer.

von F. F. (foldi)


Lesenswert?

Sven B. schrieb:
> Ja, das ist natürlich völliger Quatsch. ;)

Finde ich nicht!

Hab mal früher VB gemacht (ganz grausam damals) und nichts kommentiert, 
weil ich ein irre gutes Gedächtnis habe (oder eher hatte; der Kalk 
rieselt langsam) und nach drei Jahren konnte ich mich für Stunden 
hinsetzen um meinen eigenen Kram zu verstehen.
Heute lerne ich C und ganz im Anfang hab ich auch fast alles 
kommentiert.

Ich finde, indem man sich überlegt wie man etwas beschreibt, setzt man 
sich noch mal gesondert damit auseinander.

Leider wird in den  Büchern nicht von Anfang an auf einen gewissen Stil 
eingegangen und dann ist man schon voll drin und merkt, "Mensch,das geht 
auch anders!" und erst dann fängt man an auch mit seinem Kommentaren 
anders umzugehen.
Dazu kommt, was für dich klar ist, in deinem Kopf, das muss der Prof 
noch nicht gleich auf Anhieb sehen.

Klar,
> Nettopreis = Bruttopreis - Steuer;
ist so verständlich, dass da nichts weiter zu geschrieben werden muss.

Wichtig ist ja immer, und diese Überlegung sollte man dabei anstellen, 
muss außer mir noch jemand diesen Code verstehen oder arbeitet wohl 
möglich jemand mit mir an diesem Code?

Grundsätzlich finde ich es richtig aussagekräftige Inhalte im Code zu 
haben, aber das wird in keinem der Bücher (hab wirklich schon ne Menge 
gelesen in all den Jahren) von Anfang an vermittelt.

Deshalb ja! Kommentieren und später so, dass es aus dem Code ersichtlich 
ist oder nach den Anforderungen von Kunden und Firma, wenn man das dann 
beruflich anwenden muss.

Eine eingehende Kommentierung der Funktion oder von Main findet man fast 
immer und die sollte nie fehlen.

von F. F. (foldi)


Lesenswert?

Karl Heinz Buchegger schrieb:
> Und gegen derartige Kommentierforderungen wehre ich mich. Das ist
> sinnlos. Wenn man möchte, dann soll er von mir aus schreiben     nrWordsFound++; 
// festhalten, dass damit ein passendes Wort
>                          // mehr gefunden wurde
> Ist ok für mich, damit hab ich kein Problem. Aber notwendig wäre es
> meiner Meinung nach nicht.
Ja, für mich auch,
>Der Code spricht für sich selber.
für mich tut er das nicht. Ich hätte es nicht verstanden und das "++" 
war klar. Was du dir bei "nrWordsFound" gedacht hast, wie soll das 
jemand daraus lesen können?
Das ist es gerade was ich vorher meinte, was für mich (kann ja auch für 
viele andere) sonnenklar ist, muss für jemand anderen nicht zu erkennen 
sein.

Sicher, irgendwann hat er deine Gedankengänge verfolgen können, wenn er 
denn programmieren gelernt hat, aber wenn da was aussagekräftiges steht, 
dann braucht er nur zu lesen. Das ist es was Kommentare sollen, das 
ganze Programm lesbar machen. Denken, wie ich das ändere was da jemand 
vorher gemacht hat und das mit wenig Aufwand, das wird eine andere 
Aufgabe, die dann sicher noch genug Zeit in Anspruch nimmt.

von Mark B. (markbrandis)


Lesenswert?

Frank O. schrieb:
> Wichtig ist ja immer, und diese Überlegung sollte man dabei anstellen,
> muss außer mir noch jemand diesen Code verstehen oder arbeitet wohl
> möglich jemand mit mir an diesem Code?

Diese Frage ist praktisch immer mit JA zu beantworten.

Eine Ausnahme wäre vielleicht noch, man ist eine Ein-Mann-Firma und 
liefert nur Binaries aus, niemals Quelltext. Selbst dann kann es einem 
allerdings passieren, dass man nach Jahren mal den Code an einer 
bestimmten Stelle ändern muss und sich dann fragt, "Was hab ich denn 
da zum Teufel verzapft?"

Also: JA. Code ist sinnvoll zu schreiben (Variablennamen, 
Funktionsnamen) und sinnvoll zu dokumentieren (Kommentare, nicht zu 
viel, nicht zu wenig). Wer es anders macht, macht den Job nicht richtig.

von F. F. (foldi)


Lesenswert?

Mark Brandis schrieb:
> Frank O. schrieb:
>> Wichtig ist ja immer, und diese Überlegung sollte man dabei anstellen,
>> muss außer mir noch jemand diesen Code verstehen oder arbeitet wohl
>> möglich jemand mit mir an diesem Code?
>
> Diese Frage ist praktisch immer mit JA zu beantworten.
>
> Eine Ausnahme wäre vielleicht noch, man ist eine Ein-Mann-Firma und
> liefert nur Binaries aus, niemals Quelltext. Selbst dann kann es einem
> allerdings passieren, dass man nach Jahren mal den Code an einer
> bestimmten Stelle ändern muss und sich dann fragt, "Was hab ich denn
> da zum Teufel verzapft?"
>
> Also: JA. Code ist sinnvoll zu schreiben (Variablennamen,
> Funktionsnamen) und sinnvoll zu dokumentieren (Kommentare, nicht zu
> viel, nicht zu wenig). Wer es anders macht, macht den Job nicht richtig.

Ich mache das, im Moment wenigstens noch, nur für mich und da wäre es 
egal, aber genau, weil ich diese leidvolle Erfahrung schon vor vielen 
Jahren mit VB gemacht hatte, kann ich deine Worte nur unterstreichen.

Ein sinnvolles Fazit, deine Aussage.

von Rufus Τ. F. (rufus) (Moderator) Benutzerseite


Lesenswert?

der mechatroniker schrieb:
> Und was ist damit gewonnen gegenüber einem
>  for(zaehler=MIN; zaehler<=MAX; zaehler++){
> Letzteres entspricht nämlich dem ganz normalen for-Schleifen-Idiom, was
> man tausendmal in C-Sourcecode findet.

Das tut es nicht; in einem normalen for-schleifen-Idiom wird nicht auf 
<=, sondern auf < geprüft.

Sehe ich in einer for-Schleife ein <=, dann bekomme ich leichte Zweifel, 
ob derjenige, der das geschrieben hat, verstanden hat, wie in C mit 
Arrayindices gearbeitet wird. Klingt zunächst merkwürdig, trifft aber in 
der Kombination häufig zu.
Natürlich kann das auch legitim sein, hier ein <= hinzuschreiben, aber 
es ist eine optische Merkwürdigkeit, eine Art hervorstehender Grat, 
eine rauhe Stelle.

von Joachim D. (Firma: JDCC) (scheppertreiber)


Lesenswert?

Rufus Τ. Firefly schrieb:
> s ist eine optische Merkwürdigkeit, eine Art hervorstehender Grat,
> eine rauhe Stelle.

Die aber sofort auffällt ...

von Sven P. (Gast)


Lesenswert?

Frank O. schrieb:
> Ja, für mich auch,
>>Der Code spricht für sich selber.
> für mich tut er das nicht. Ich hätte es nicht verstanden und das "++"
> war klar. Was du dir bei "nrWordsFound" gedacht hast, wie soll das
> jemand daraus lesen können?
Da hilft aber auch ein Kommentar nicht mehr.

Offensichtlicher als die Variable mit 'nrWordsFound' zu bezeichnen, geht 
es ja wirklich nicht mehr. Ich finde, man darf vom Leser eines 
Quelltextes durchaus erwarten, dass er in der Lage ist, solche einfachen 
Schlussfolgerungen alleine zu ziehen. Es ist unsinnig, einen Quelltext 
so zu kommentieren, dass man ihn beim ersten Blick sofort versteht, ohne 
den Zusammenhang zu kennen. Damit ist niemandem geholfen und es macht 
die Programmierung fürchterlich und unnötig umständlich.

Kommentare sollen da weiterhelfen, wo der Quelltext Annahmen trifft, die 
nicht offensichtlich sind. Sie sollen nicht den Quelltext nacherzählen.

Irgendwo ist auch m.M.n. eine Grenze, wo man sagen sollte: Jemand, der 
die Programmiersprache überhaupt nicht beherrscht, der hat am Quelltext 
erstmal nichts verloren. Andernfalls läuft das meistens auf eine 
schwachsinnige Argumentation raus wie 'Hätten die Basic benutzt, 
hätten wir es verstanden. Aber geschweifte Klammern versteht doch 
keiner.' ...

Ich bilde mir ja auch nicht ein, mein Moped vernünftig lackieren zu 
können, weil auf den Lackdosen so eine tolle Gebrauchsanweisung steht. 
Das ist einfach irsinnig.

von Mark B. (markbrandis)


Lesenswert?

Sven P. schrieb:
> Offensichtlicher als die Variable mit 'nrWordsFound' zu bezeichnen, geht
> es ja wirklich nicht mehr.

NumberOfWordsFound

number_of_words_found

:-)

von Sven P. (Gast)


Lesenswert?

Ja, ja.
1
int theNumberOfWordsThatHaveBeenFoundSoFar;
2
int javaStyleVariableNamesAreAsBloodyAsCamelCaseNames;
3
gtk_tree_view_column_get_sort_column_id();
4
GetTextEffectCharacterIndexFromTextSourceCharacterIndex(); /* (1) */

(1) 
http://msdn.microsoft.com/de-de/library/system.windows.media.textformatting.textsource.gettexteffectcharacterindexfromtextsourcecharacterindex%28v=vs.85%29.aspx


Das machts weder lesbarer noch verständlicher.

von Rufus Τ. F. (rufus) (Moderator) Benutzerseite


Lesenswert?

Sven P. schrieb:
> Das machts weder lesbarer noch verständlicher.

Gewiss. Aber wie so oft liegt die Wahrheit in der Mitte.

von Sven B. (scummos)


Lesenswert?

Frank O. schrieb:
> Sven B. schrieb:
>> Ja, das ist natürlich völliger Quatsch. ;)
> Finde ich nicht!

Um nochmal zu klarifizieren was ich als Quatsch bezeichnet habe, ich 
meinte damit diese Art, jedes Stück Code durch Kommentare in ein 
Tutorial für die betreffende Programmiersprache zu verwandeln. 
Ausführliches Kommentieren finde ich bei einigen Sachen unnötig, weil 
ich finde, es geht aus dem Code klar hervor, was genau passiert. Das 
heißt aber nicht, dass ich militant dagegen bin, auch einfache 
Algorithmen ausführlich zu kommentieren; wer Lust hat, kann das gern tun 
-- solange, die Kommentare erläutern, was, wie und warum der Code tut, 
und nicht die Syntax der Sprache erklären.
Ansonsten kann ich an Deinen Aussagen nichts finden, dem ich 
widersprechen würde.

Grüße,
Sven

von Joachim D. (Firma: JDCC) (scheppertreiber)


Lesenswert?

... und dann noch politisch korrekten barrierefreien Sourcecode
für Behinderte, Leute mit Sehschwächen und Gehörlose ...

von Sven B. (scummos)


Lesenswert?

Joachim Drechsel schrieb:
> ... und dann noch politisch korrekten [...] Sourcecode
http://www.vidarholen.net/contents/wordcount/

von Joachim D. (Firma: JDCC) (scheppertreiber)


Lesenswert?

Sven B. schrieb:
> Joachim Drechsel schrieb:
>> ... und dann noch politisch korrekten [...] Sourcecode
> http://www.vidarholen.net/contents/wordcount/

:-)))

von F. F. (foldi)


Lesenswert?

Mark Brandis schrieb:
> Sven P. schrieb:
>> Offensichtlicher als die Variable mit 'nrWordsFound' zu bezeichnen, geht
>> es ja wirklich nicht mehr.
>
> NumberOfWordsFound
>
> number_of_words_found
>
> :-)

Genau!!!! :-)
Hätte auch heißen können "nicht richtige Wörter gefunden"

Was ich allerdings glaube, und ich mache das auch zwischendurch so, dass 
man schnell am etwas "a1" nennt, weil es halt schneller getippt ist als 
"antriebsMotor_1" (nur plakatives Beispiel) und ruck zuck kann man das 
selbst nicht mehr lesen.
Zu viel ist zu viel, da bin ich bei euch und auch bei den eindeutigen 
Variablennamen bin ich dabei, aber war Eingangs nicht von der Uni die 
Rede?
Das sind doch alles Mädels und Jungs die das noch lernen wollen (so wie 
ich) und wenn einem nicht schon ein paar mal so einen Zählerschleife 
begegnet ist, dann ist es schon sinnvoll da was hinter zu schreiben.

state = 1 - state;

Ohne Erklärung hätte ich da anfangs ziemlich doof und lange überlegt.

Vielleicht kann man sich darauf einigen: anfangs mehr, später weniger.

von Der Rächer der Transistormorde (Gast)


Lesenswert?

Frank O. schrieb:
>> Nettopreis = Bruttopreis - Steuer;
> ist so verständlich, dass da nichts weiter zu geschrieben werden muss.

Zur Zeit lerne ich C, bitte daher um mildernde Umstände wenn ich 
Blödsinn schreibe.

Nettopreis = Bruttopreis - Steuer; // ist für mich unvollständig

Ohne den Variablentypen im Kopf zu haben kann doch keiner Wissen ob das 
Ergebnis auch richtig ist. Da ich mir so was sowieso nicht merken kann 
schreibe ich (Als Beispiel keine Ahnung ob ein compiler das korrekt 
castet)

lNettopreis = dBruttopreis - fSteuer;  // wobei l für long, d für double 
f für float steht.

Wie macht das ein Profi? Hat der die ganzen Typendeklarationen im Kopf?

von B. S. (bestucki)


Lesenswert?

Bei uns in der Firma ist vorgeschrieben, wie Variablennamen auszusehen 
haben. Es gibt eine Liste, die verschiedene Abkürzungen wie z.b. Nbr 
(Number (of)), Val (Value), Cntr (Counter) usw. definiert. Dabei ist 
auch die Reihenfolge der Abkürzungen relevant. NbrVal (Number of Values, 
Anzahl der Werte) ist nicht das selbe wie ValNbr (Value Number, Nummer 
des Werts).

Zu den Datentypen:
Die Datentypen sind immer am Anfang jedes Blocks ersichtlich. Daher ist 
es unsinnig, den Datentyp in den Variablennamen zu schreiben. 
Grundsätzlich muss darauf geachtet werden, dass die Datentypen 
verlustfrei umgewandelt werden, h.d. immer von einem gleichen zum 
gleichen oder von einem kleineren zum grösseren Datentyp. Es gibt einige 
Ausnahmen, dort muss kommentiert werden.

von Thomas (Gast)


Lesenswert?

Das macht heutzutage kein Mensch mehr.
Moderne IDEs zeigen dir die Deklaration an, wenn du mit der Maus drüber 
fährst.

Genau so ein Unsinn wie 70 Zeichen pro Zeile.
Früher sinnvoll, heute nicht mehr.

von Sven P. (Gast)


Lesenswert?

Der Rächer der Transistormorde schrieb:
> Zur Zeit lerne ich C, bitte daher um mildernde Umstände wenn ich
> Blödsinn schreibe.
>
> Nettopreis = Bruttopreis - Steuer; // ist für mich unvollständig
>
> Ohne den Variablentypen im Kopf zu haben kann doch keiner Wissen ob das
> Ergebnis auch richtig ist.
Keiner verlangt von dir, die im Kopf zu haben. Du darfst jederzeit in 
der Definition der Variablen nachschauen.

Ich programmiere nun schon zehn Jahre und muss trotzdem quasi jede 
dritte Funktion der C-Standardbibliothek nachschlagen, bevor ich sie 
verwende. Das ist keine Schande, ich merke mir lieber wichtigere Dinge. 
Und es ist in jedem Fall besser, als sich (möglicherweise überheblich) 
auf sein vermeintliches Wissen zu verlassen.


> Da ich mir so was sowieso nicht merken kann
> schreibe ich (Als Beispiel keine Ahnung ob ein compiler das korrekt
> castet)
>
> lNettopreis = dBruttopreis - fSteuer;  // wobei l für long, d für double
> f für float steht.
>
> Wie macht das ein Profi? Hat der die ganzen Typendeklarationen im Kopf?
So jedenfalls nicht. Was du da meinst, ist die sogenannte /ungarische 
Notation/ nach Simonyi. Die Idee davon ist es, den Variablen ein Kürzel 
voranzustellen, welches den Typ der Variablen beschreibt.

Nun hat, allen voran, Microsoft da allerdings wieder nur mit halben Ohr 
zugehört und daraus eine Perversion gemacht, die numehr das komplette 
Win-API durchseucht hat: Sie haben Typ als Datentyp interpretiert 
und nun klemmt vor jedem Parameter halt 'dw' für 'Doppelwort', 'lpctstr' 
für 'long pointer to const TCHAR string'. Eben das, was du da im 
Beispiel auch gemacht hast.

Das hatte Simonyi eigentlich nicht gewollt. Mit Typ meinte er nämlich 
sowas wie Zählvariable oder Anzahl oder Flag.


Frag dich doch selbst: Was hast du davon, jeder Variable den Typen 
voranzustellen? Genau, jede Menge Arbeit, wenn der Typ geändert werden 
muss. Abgesehen vom Win-API ist mir die Konvention in freier Wildbahn 
auch noch nirgendwo begegnet.

von Sven P. (Gast)


Lesenswert?

Nachtrag.

Es gibt alte Konventionen, die heute noch sinnvoll sind. Zum Beispiel, 
nach 70 Spalten mal einen Zeilenumbruch zu setzen. Früher war das nötig, 
weil Lochkarten halt nur 40/70/... Zeichen breit waren. Heute halte ich 
das nach wie vor für sinnvoll, weil es etwas Disziplin in den Quelltext 
bringt. Wenn mir eine Zeile über 70 Spalten wächst, ist das meistens ein 
sehr gutes Argument, die Zeile zu überdenken, lokale Variablen für 
Zwischenergebnisse einzuziehen und so weiter. Lesber ist das ansonsten 
nämlich nicht mehr.

Genauso gibt es viele neue Konventionen, die ich für Blödsinn halte. 
Quelltext wird weder lesbarer noch sicherer noch wartbarer, wenn man 
stupide irgendwelche Bezeichnungschema für Variablen und Funktionsnamen 
anwendet. Allen voran käme da MISRA-C. Das ist auch so ein (teilweise) 
akademischer Regelsatz, den die ganze (Automobil-)Industrie ganz toll 
findet und m.M.n. stellenweise überbewertet.
Eine Programmiersprache wird nicht sicherer, wenn man sie an allen 
Enden kastriert und so den Programmierer zwingt, total unnötige 
Work-arounds zu erfinden, um damit Regeln einzuhalten. Eher im 
Gegenteil.

Das ist ein ganz furchtbar zweischneidiges Schwert. Richtig angewendet, 
bringen solche Regeln sehr viel. Stupide abgespult bringen sie 
garnichts.

von Der Rächer der Transistormorde (Gast)


Lesenswert?

Sven P. schrieb:
> Ich programmiere nun schon zehn Jahre und muss trotzdem quasi jede
> dritte Funktion der C-Standardbibliothek nachschlagen, bevor ich sie
> verwende.

Sehr beruhigend ;-), danke auch für die anderen Erklärungen.

> Was hast du davon, jeder Variable den Typen
> voranzustellen? Genau, jede Menge Arbeit, wenn der Typ geändert werden
> muss.

Verstanden, das ist ein KO-Kriterium aber ich bin ja noch am probieren

be stucki schrieb:
> Es gibt eine Liste, die verschiedene Abkürzungen wie z.b. Nbr
> (Number (of)), Val (Value), Cntr (Counter) usw. definiert. Dabei ist
> auch die Reihenfolge der Abkürzungen relevant.

Auch hier schönen Dank. Wenn ich das richtig verstehe wird die Intention 
(bzw. Funktion) der Variable standardisiert. Bewährt sich das in der 
Praxis?

Was ist z.B. mit dem int i; ? Das würde ich z.B. immer als Abk. für 
einen Schleifenzähler sehen.

von Sven P. (Gast)


Lesenswert?

Der Rächer der Transistormorde schrieb:
>> Was hast du davon, jeder Variable den Typen
>> voranzustellen? Genau, jede Menge Arbeit, wenn der Typ geändert werden
>> muss.
>
> Verstanden, das ist ein KO-Kriterium aber ich bin ja noch am probieren
KO nicht ganz, moderne IDE haben ja Refactoring-Funktionen, etwa 
'Variable projektweit umbenennen'. Aber m.M.n. ist schon die 
Notwendigkeit, sowas zu tun, überflüssig.


> Was ist z.B. mit dem int i; ? Das würde ich z.B. immer als Abk. für
> einen Schleifenzähler sehen.
Garnichts ist damit. Hattest du bisher irgendein Problem damit, die 
Variable 'i' unmittelbar einem Schleifenzähler zuzuordnen? Siehste.
Eher wirst du kurz innehalten, wenn du ein 'i' liest aber keine Schleife 
findest.

Das sind beispielsweise solche C-typischen Idiome. Hat Georg weiter oben 
ja auch schon beschrieben.

von B. S. (bestucki)


Lesenswert?

Der Rächer der Transistormorde schrieb:
> Auch hier schönen Dank. Wenn ich das richtig verstehe wird die Intention
> (bzw. Funktion) der Variable standardisiert. Bewährt sich das in der
> Praxis?
Hier geht es eher darum, dass alle im Team die Variablen gleich 
benennen. Man erkennt schneller, für was diese Variable eingesetzt wird, 
wenn sich dann auch alle konsequent daran halten...

Der Rächer der Transistormorde schrieb:
> Was ist z.B. mit dem int i; ? Das würde ich z.B. immer als Abk. für
> einen Schleifenzähler sehen.
i, j, k, m, n sind (für mich) alles Schleifenzähler, aber nichts 
anderes!

von Joachim D. (Firma: JDCC) (scheppertreiber)


Lesenswert?

be stucki schrieb:
>> Was ist z.B. mit dem int i; ? Das würde ich z.B. immer als Abk. für
>> einen Schleifenzähler sehen.

Irgendwie hat sich das bei mir auch so "eingebürgert":

i, k etc sind immer Schleifenzähler
p, q etc sind immer Pointer

von der mechatroniker (Gast)


Lesenswert?

Hat schon jemand die Regel "je größer der Scope, desto länger der Name" 
erwähnt?

Eine lokale Variable in einem 10 Zeilen langen Block, die offensichtlich 
als Schleifenzähler verwendet wird, darf i heißen (und man u.U. das 
"darf" sogar durch ein "sollte" ersetzen, wenn dadurch Ausdrücke nicht 
unnötig in die Länge gezogen werden und damit lesbarer bleiben), eine 
Membervariable einer Klasse, egal wofür sie benutzt wird, tunlichst 
nicht.

von Detlev T. (detlevt)


Lesenswert?

Kommentare sind unverzichtbar! Wichtig sind aus meiner Sicht vor allem 
die Beschreibung der Schnittstellen von Funktionen sowie die Aufgaben 
und Methoden von Objekten, wenn man objektorientiert programmiert. Also 
das, was man "von außen" nutzen könnte.

Ich benutze dafür Natural Docs, das ähnlich wie doxygen automatisiert 
Dokumentationen erstellen kann, im Quelltext aber für Menschen noch sehr 
gut lesbar ist. IMO kann auch der beste dokumentierte Quelltext keine 
Dokumentation ersetzen. (und umgekehrt)

von Sven B. (scummos)


Lesenswert?

Diese dämlichen Konventionen mit "ein Float muss mit f beginnen" sollte 
man lieber nicht benutzen. Die machen den Code total unlesbar (weil 
ständig diese nervigen Kürzel irgendwo rumstehen), und jede vernünftige 
IDE weiß eh, welchen Typ die Variablen haben.

Was das 70-Zeichen-Limit angeht, ja, es ist sinnvoll, ein Limit für die 
Zeilenlänge zu haben, aber ich würde das statt 70 eher auf 110 oder 120 
setzen. Das ist irgendwie zeitgemäßer. Mit 120 Zeichen passen auf 
heutigen Bildschirmen immer noch zwei Spalten nebeneinander.

Grüße,
Sven

von Rolf M. (rmagnus)


Lesenswert?

Karl Heinz Buchegger schrieb:
> Du hast 3) vergessen
>
> 3) Die Variablen- und Funktionsnamen sind nicht gerade selbsterklärend,
> und die Kommentare sind nichtssagend und bisweilen sogar falsch.

Das ist das Hauptproblem bei Kommentaren: Wenn der Code geändert wird, 
wird oft vergessen, den Kommentar anzupassen. Und sehr viel schlimmer 
als gar kein Kommentar ist ein Kommentar, der nicht zum Code paßt.

asmhobbyist schrieb:
> Ich denke, generell ist mehr besser als weniger, denn man übt sich ja
> auch im Kommentieren.

Sehe ich anders, gerade aus dem oben genannten Grund, und außerdem, weil 
man dan zusätzlich zum Code immer noch die Kommentare lesen muß. Wenn 
die nichts enthalten, das im Code nicht auch schon ersichtlich war, 
kostet das nur unnötig Zeit beim Lesen. Zuviele Kommentare schaden der 
Lesbarkeit des Codes und lenken vom Wesentlichen eher ab.

Detlev T. schrieb:
> Kommentare sind unverzichtbar! Wichtig sind aus meiner Sicht vor allem
> die Beschreibung der Schnittstellen von Funktionen sowie die Aufgaben
> und Methoden von Objekten, wenn man objektorientiert programmiert. Also
> das, was man "von außen" nutzen könnte.

Das ist eine andere Art von Kommentar, als die, über die hier diskutiert 
wird.
Die Funktonsbeschreibungen, insbesondere auch mit Parameter und 
Besonderheiten, auf die bei Benutzung zu achten ist, ist auf jeden Fall 
sinnvoll.

> Ich benutze dafür Natural Docs, das ähnlich wie doxygen automatisiert
> Dokumentationen erstellen kann, im Quelltext aber für Menschen noch sehr
> gut lesbar ist.

Sind Doxygen-Kommentare das nicht?

von adsf (Gast)


Lesenswert?

In der Uni haben wir jetzt mal bei einem größeren Projekt die Aufgabe 
bekommen Kommentare soweit irgendwie möglich zu vermeiden. Ist auch ganz 
spannend, da dann wirklich der Code an sich sprechend sein muss und man 
nicht einfach einen kryptischen Ausdruck mit einem "hingerotzten" 
Kommentar der sagt was da passieren soll erschlagen kann, sondern den 
Ausdruck schöner strukturieren muss, oder ihn in Funktionen mit 
sprechenden Namen zerlegen muss. Sehr lehrreich, auch wenn es einem 
zuerst widerstrebt so lange Namen zu benutzen oder Funktionen so 
kleinteilig zu zerlegen.
Das war allerdings nicht C, sondern Smalltalk, da ist der Quelltext dann 
trotzdem noch relativ kompakt.

von Detlev T. (detlevt)


Lesenswert?

Rolf Magnus schrieb:
>> Ich benutze dafür Natural Docs, das ähnlich wie doxygen automatisiert
>> Dokumentationen erstellen kann, im Quelltext aber für Menschen noch sehr
>> gut lesbar ist.
>
> Sind Doxygen-Kommentare das nicht?

Aus meiner Sicht nicht. Die Formatierungen stören den Lesefluss doch 
sehr. Bei Natural Docs sieht ein Beispiel so aus:
1
/*
2
   Function: Multiply
3
4
   Multiplies two integers.
5
6
   Parameters:
7
8
      x - The first integer.
9
      y - The second integer.
10
11
   Returns:
12
13
      The two integers multiplied together.
14
15
   See Also:
16
17
      <Divide>
18
*/
Bei Doxygen würde das wohl so aussehen:
1
/**
2
 * @brief Multiplies two integers.
3
 * @param x The first integer
4
 * @param y The second integer.
5
 * @return The two integers multiplied together.
6
 * \sa {Divide} 
7
*/
Deutlich kompakter, was schon ein Vorteil ist, aber doch stark 
gewöhnungsbedürftig.

von Sven P. (Gast)


Lesenswert?

Mit nem anständigen Editor wird die Doxygen-Syntax noch hervorgehoben, 
dann siehts schon ansehnlicher aus.

Bei NaturalDocs stört mich, dass es syntaktisch festgefahren ist. Es 
gibt Schlüsselwörter für 'int' und 'double' und so weiter, aber keine 
für 'uint32_t' etc. Doxygen ist da deutlich allgemeiner gefasst.

Dafür hat Doxygen andere nervtötende Eigenheiten (Gruppieren...)

von Sven B. (scummos)


Angehängte Dateien:

Lesenswert?

Ein normaler Editor macht hübsches Highlighting für Doxygen (was bei 
Doxygen übrigens viel leichter ist als bei so einer 
Umgangssprache-Syntax!), dann kann man das auch sehr gut lesen ;)

von asmhobbyist (Gast)


Lesenswert?

der mechatroniker schrieb:
>
1
 for(zaehler=MIN; zaehler<=MAX; zaehler=zaehler +1){
 >Und was ist damit gewonnen gegenüber einem
1
for(zaehler=MIN; zaehler<=MAX; zaehler++){
> ?

Ich hatte ja auf einen netten Kommentar (im code) zur "Bruchstelle" 
gehofft ;)

Wenn du in der oberen Zeile den für MAX den Maximalwert des Datenformats 
eingibst, dann ist  i= i+1 eine nette Visualisiserung...

Der Vorteil bestimmter Muster ist natürlich auch die so wohltuende 
Standardisierung. Auch hier kann man gucken, ob man lieber mit 
standardisierten Einzelbuchstaben rummacht, oder lesehilfreich coded.

Ich bin öfter überrascht, wenn ich selber meine, mit standardkürzeln 
coden zu müssen, und gar nicht nachdenke, und dann sehe ich mal guten 
selbbstredenden Code und denke: Aha... da war doch wieder einer schlauer 
als ich Grobcoder für arme Abgucker.

von Rufus Τ. F. (rufus) (Moderator) Benutzerseite


Lesenswert?

asmhobbyist schrieb:
> Wenn du in der oberen Zeile den für MAX den Maximalwert des Datenformats
> eingibst, dann ist  i= i+1 eine nette Visualisiserung...

Was möchstest Du mit diesem Satz sagen?

von Kaj (Gast)


Lesenswert?

Ich durfte mal an einer C++-Weiterbildung teilnehmen... noch am ersten 
Tag wollte ich den Seminarleiter erschlagen. Warum?
Er war der Meinung: 1/3 Code, 2/3 Kommentare... und das meinte der echt 
ernst! Das sah in der Praxis dann so aus:
1
class myClass
2
{
3
  public:
4
    //Konstruktor
5
    myClass(void);
6
7
    //Destruktor
8
    ~myClass(void);
9
10
    //Memberfunktion
11
    void foo1(void);
12
13
    //Membervariable
14
    int myVar;
15
};
Ich denke man kann es echt hart übertreiben mit unnötigen Kommentaren...

von Mr.T (Gast)


Lesenswert?

Sven P. schrieb:
> Das 'muss' ist falsch. Kommentieren müssen ist mindestens genauso
> bescheuert wie garnicht zu kommentieren. Wobei garnicht kommentierte
> Quelltexte dann meistens noch weniger Fragen offen lassen, als solche,
> die kommentiert werden mussten.

Sehe ich genau so.
Zur Frage des TE:
das ist sehr unterschiedlich. Ich habe in einer 8Personen Klitsche 
gearbeitet, da war alles "historisch gewachsen" :-( Rest kannst Du Dir 
denken. In einer 50Pers. Firma sah es ähnlich schlimm aus.
Jetzt in einer 1000Pers. Firma ist da deutlich mehr Struktur drin. Jede 
Funktion erhält einen Kommentarblock darüber. Da haben wir quasi eine 
standardisierte Schablone für. Ansonsten wird bei Code-Reviews 
nachkommentiert, wenn dem Reviewer etwas unklar ist, d.h. nur der 
Programmierer kapiert seinen Algorithmus.
Je größer die Firma, desto wahrscheinlicher findest Du Coding-Rules 
(z.B. MISRA) und Style-Guides (Indian Hill z.B.)

von Rolf M. (rmagnus)


Lesenswert?

Kaj schrieb:
> Er war der Meinung: 1/3 Code, 2/3 Kommentare... und das meinte der echt
> ernst!

Ich habe im Studium in der Vorlesung über OOP noch ein extremeres 
Beispiel erlebt. In seinem Manuskript mußte man (auch manels 
Syntax-Highlighting) ungelogen den Code zwischen den Kommentaren suchen, 
weil nur ab und zu vereinzelt mal eine echte Codezeile vorkam. Und er 
war auch der festen Überzeugung, daß das nicht nur in seinen 
Codebeispielen, sondern immer so sein muß.

von asmhobbyist (Gast)


Lesenswert?

Rufus Τ. Firefly schrieb:
> asmhobbyist schrieb:
>> Wenn du in der oberen Zeile den für MAX den Maximalwert des Datenformats
>> eingibst, dann ist  i= i+1 eine nette Visualisiserung...
>
> Was möchstest Du mit diesem Satz sagen?
Entschuldige, Rufus, wenn ich jetzt erst antworte. Ich hatte Ärger mit 
meinem Browser(n), und unten beim Nachrichten abschicken wurde 
angezeigt, dass meine IP gesperrt ist. So hatte ich gedacht, dass ich 
vielleicht spamme. Möchte ich aber nicht wirklich.

Der Code oben hat das Problem, dass das maximale Datenformat wie bei 
z.B. 8 Bit = 255d nicht + 1 nach oben zählen kann, und der Loop so zu 
einer Endlosschleife wird (weswegen es auch sinnvoller ist, lieber immer 
einen drunter zu bleiben, bzw. kleiner und nicht (kleiner oder gleich) 
zu setzen).

von Axel L. (axel_5)


Lesenswert?

Rolf Magnus schrieb:
> Kaj schrieb:
>> Er war der Meinung: 1/3 Code, 2/3 Kommentare... und das meinte der echt
>> ernst!
>
> Ich habe im Studium in der Vorlesung über OOP noch ein extremeres
> Beispiel erlebt. In seinem Manuskript mußte man (auch manels
> Syntax-Highlighting) ungelogen den Code zwischen den Kommentaren suchen,
> weil nur ab und zu vereinzelt mal eine echte Codezeile vorkam. Und er
> war auch der festen Überzeugung, daß das nicht nur in seinen
> Codebeispielen, sondern immer so sein muß.

Ja, und ?

Zu viel Kommentar ist in Minuten entfernt.

Zu wenig Kommentar braucht u. U. Tage zum ergänzen, teilweise wird 
Software lieber neugeschrieben.

Gruss
Axel

von Sven P. (Gast)


Lesenswert?

Axel Laufenberg schrieb:
> Zu viel Kommentar ist in Minuten entfernt.
>
> Zu wenig Kommentar braucht u. U. Tage zum ergänzen, teilweise wird
> Software lieber neugeschrieben.
Das ist dann aber auch meistens dringenst nötig...

Wenn ein Quelltext sich in der Kommentierung irgendwelcher Banalitäten 
ergießt, naja. Muss ich nicht haben. Müssen die meisten Leute nicht 
haben.

von Vlad T. (vlad_tepesch)


Lesenswert?

asmhobbyist schrieb:
> Der Code oben hat das Problem, dass das maximale Datenformat wie bei
> z.B. 8 Bit = 255d nicht + 1 nach oben zählen kann,

Das Problem des Codes hat sicherlich nahezu jeder hier verstanden.

Ich glaub Rufus Fragestellung galt dem Teilsatz:

asmhobbyist schrieb:
> dann ist  i= i+1 eine nette Visualisiserung...

den ich übrigens auch nicht verstanden habe, was daran liegen könnte, 
dass du den Begriff 'Visualisierung' falsch verwendest.
Es ergibt so auf jeden Fall keinen Sinn.

von Vlad T. (vlad_tepesch)


Lesenswert?

Axel Laufenberg schrieb:
> Zu viel Kommentar ist in Minuten entfernt.

und wie lange braucht es, die Synchronität zwischen Code und Kommentar 
zu validieren, bzw zu bemerken, dass diese längst verloren wurde?

von Axel L. (axel_5)


Lesenswert?

Sven P. schrieb:
> Wenn ein Quelltext sich in der Kommentierung irgendwelcher Banalitäten
> ergießt, naja. Muss ich nicht haben. Müssen die meisten Leute nicht
> haben.

Ich schon. Was im Zweifel bedeutet, dass Du in einem meiner Projekte 
nicht zum Zuge kommen würdest. Ich habe schon Leute wegen einer solchen 
Einstellung abgelehnt.

Das ist für Dich jetzt erstmal nicht schlimm, aber ich stelle fest, dass 
viele Projektleiter das zunehmend ähnlich sehen. Spätestens wenn dann 
während des Urlaubs des ursprünglichen Autoren mal was geändert werden 
muss, stellt man nämlich fest, wie wichtig eine ausführliche 
Kommentierung ist.

Ich bin damit einmal richtig auf die Nase gefallen, seitdem ziehe ich 
das konsequent durch. Das war auch so ein Programmiergott, dessen Code 
selbsterklärend und fehlerfrei war.

Gruss
Axel

von Axel L. (axel_5)


Lesenswert?

Vlad Tepesch schrieb:
> Axel Laufenberg schrieb:
>> Zu viel Kommentar ist in Minuten entfernt.
>
> und wie lange braucht es, die Synchronität zwischen Code und Kommentar
> zu validieren, bzw zu bemerken, dass diese längst verloren wurde?

Ich lasse da ja kein Script drüber laufen, welches alle Kommentare 
löscht.

Aber ich habe dann die Wahl, was ich lösche. Das Original habe ich ja 
dann immer noch.

Gruss
Axel

von Sven P. (Gast)


Lesenswert?

Axel Laufenberg schrieb:
> Sven P. schrieb:
>> Wenn ein Quelltext sich in der Kommentierung irgendwelcher Banalitäten
>> ergießt, naja. Muss ich nicht haben. Müssen die meisten Leute nicht
>> haben.
>
> Ich schon. Was im Zweifel bedeutet, dass Du in einem meiner Projekte
> nicht zum Zuge kommen würdest. Ich habe schon Leute wegen einer solchen
> Einstellung abgelehnt.
>
> Das ist für Dich jetzt erstmal nicht schlimm, aber ich stelle fest, dass
> viele Projektleiter das zunehmend ähnlich sehen. Spätestens wenn dann
> während des Urlaubs des ursprünglichen Autoren mal was geändert werden
> muss, stellt man nämlich fest, wie wichtig eine ausführliche
> Kommentierung ist.
Naja, ich will dir da sicherlich nicht reinreden, du weißt schon, was du 
tust.

Generell spricht es aber nicht unbedingt für einen Projektleiter, wenn 
er auf sowas  beharrt. Die allermeisten richtig (objektiv) guten 
Programmierer schreiben Programmtext mit wenig Kommentar, der trotzdem 
einwandfrei lesbar ist. Und alle diese schließt du wegen eines - mit 
Verlaub - meiner Meinung nach völlig absurden 'Qualitätsmerkmals' aus.
Nun wie gesagt, ist dein Bier. Aber das solltest du, denke ich, mal im 
Hinterkopf behalten.

> Ich bin damit einmal richtig auf die Nase gefallen, seitdem ziehe ich
> das konsequent durch. Das war auch so ein Programmiergott, dessen Code
> selbsterklärend und fehlerfrei war.
Das so zu pauschalisieren, finde ich nicht richtig. Ich verspreche dir 
außerdem hoch und heilig, dass du mit Erzählkommentaren genauso auf die 
Nase gefallen wärst.

Es gibt gewiss Leute, die schreiben unkommentierten Humbug hin, 
möglichst verklausuliert, und finden das toll und schmollen, wenn man 
sie kritisiert. Sowas meinst du vermutlich. Das ist aber umgekehrt nicht 
automatisch ein Argument für Kommentare.

Les halt mal Linux-Kernelquellen(1). Keine Sau kommentiert da solche 
Banalitäten. Obwohl ich von Kernelentwicklung überhaupt keine Ahnung 
habe, fühle ich mich in den Quellen zurecht und wohl - in weiten Zügen 
ist der Quelltext problemlos nachvollziehbar. Kommentare beschränken 
sich darauf, wichtige Sachverhalte zu klären und plappern nicht den 
Quelltext nach.

Und das funktioniert nun schon etliche Jahre mit unzähligen 
Programmierern, und zwar durchaus echt fähigen Programmierern. Auch 
Programmierern, die quereinsteigen und/oder nach langer Pause wieder 
einen Fuß fassen. Und nun bestehst du wirklich auf kommentierte 
Banalität?!

Und ja, ich bin auch ein Freund von ausführlich und sauber 
durchkommentierten Schnittstellen. Sowas muss eindeutig und vollständig 
sein, es darf/sollte keine Unklarheiten wegen 'aber was passiert 
eigentlich wenn...' offen lassen.


(1) http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=tree

von Sven P. (Gast)


Lesenswert?

Axel Laufenberg schrieb:
> Vlad Tepesch schrieb:
>> Axel Laufenberg schrieb:
>>> Zu viel Kommentar ist in Minuten entfernt.
>>
>> und wie lange braucht es, die Synchronität zwischen Code und Kommentar
>> zu validieren, bzw zu bemerken, dass diese längst verloren wurde?
>
> Ich lasse da ja kein Script drüber laufen, welches alle Kommentare
> löscht.
>
> Aber ich habe dann die Wahl, was ich lösche. Das Original habe ich ja
> dann immer noch.
Du musst aber für jeden Eingriff sofort zwei Stellen finden, lesen und 
verstehen.

Es sei denn natürlich, du vertraust blind den Kommentaren. Nur haben die 
jene Eigenheit, sich später nicht im Programm bemerkbar zu machen.

Und wenn da dann ein Fehler auffält, musst du dir wieder Gedanken 
machen, ob der Quelltext falsch ist und nicht das macht, was er laut 
Kommentar machen soll, oder ob der Quelltext verändert wurde und der 
Kommentar vergessen. Das ist Redundanz... ein Problem, welches man in 
jeder (relationalen) Datenbank aus genau diesem Grund zu vermeiden 
versucht. Das nennt man dann Normalisierung.

von Axel (Gast)


Lesenswert?

Sven P. schrieb:
> Axel Laufenberg schrieb:
> ...
> Les halt mal Linux-Kernelquellen(1). Keine Sau kommentiert da solche
> Banalitäten. Obwohl ich von Kernelentwicklung überhaupt keine Ahnung
> habe, fühle ich mich in den Quellen zurecht und wohl - in weiten Zügen
> ist der Quelltext problemlos nachvollziehbar.
Wenn Du das sagst.

>
> Und das funktioniert nun schon etliche Jahre mit unzähligen
> Programmierern, und zwar durchaus echt fähigen Programmierern. Auch
> Programmierern, die quereinsteigen und/oder nach langer Pause wieder
> einen Fuß fassen. Und nun bestehst du wirklich auf kommentierte
> Banalität?!
Ja, die machen auch nichts anderes. Davon abgesehen ist das Zeugs ja 
alles andere als auf Anhieb Bugfrei, bzw. es hat Jahre gedauert, bis es 
fehlerfrei lief.

> Und ja, ich bin auch ein Freund von ausführlich und sauber
> durchkommentierten Schnittstellen. Sowas muss eindeutig und vollständig
> sein, es darf/sollte keine Unklarheiten wegen 'aber was passiert
> eigentlich wenn...' offen lassen.
>
> (1) http://git.kernel.org/?p=linux/kernel/git/torvalds...

So beim ersten Durchscrollen finde ich da weder sauber dokumentierte 
Schnittstellen noch sonstwelche Kommentare.

>Und wenn da dann ein Fehler auffält, musst du dir wieder Gedanken
>machen, ob der Quelltext falsch ist und nicht das macht, was er laut
>Kommentar machen soll, oder ob der Quelltext verändert wurde und der
>Kommentar vergessen. Das ist Redundanz... ein Problem, welches man in
>jeder (relationalen) Datenbank aus genau diesem Grund zu vermeiden
>versucht. Das nennt man dann Normalisierung.

Durch die Redundanz kann man wesentlich schneller überprüfen, ob der 
Code das tut, was er soll und was sich der Entwickler gedacht hat. Wenn 
es bei der Revision Diskrepanzen gibt, muss das geprüft und behoben 
werden. Das ist kein Nachteil, das ist ein Vorteil, der teure Fehler 
verhindern hilft.

> Generell spricht es aber nicht unbedingt für einen Projektleiter, wenn
> er auf sowas  beharrt. Die allermeisten richtig (objektiv) guten
> Programmierer schreiben Programmtext mit wenig Kommentar, der trotzdem
> einwandfrei lesbar ist. Und alle diese schließt du wegen eines - mit
> Verlaub - meiner Meinung nach völlig absurden 'Qualitätsmerkmals' aus.
> Nun wie gesagt, ist dein Bier. Aber das solltest du, denke ich, mal im
> Hinterkopf behalten.

Ich komme ursprünglich aus der ASIC-Entwicklung. Da kann man nicht 
einfach mal eine neue CD rausschicken, wenn Fehler drin sind. Da kostet 
jeder Fehler richtig, richtig Geld.

DAS habe ich im Hinterkopf. Jedesmal, wenn ich einem Kunden erklärt 
habe, dass wir leider einen Bug im Chip haben und immense Kosten und 
Verzögerungen auf ihn zukommen.

Ziel ist es also nicht, schönen Code abzuliefern, Ziel ist es 
fehlerfreien Code abzuliefern. Die von Dir angeprangerte Redundanz ist 
dafür ein entscheidendes Hilfsmittel.

Das sollte eigentlich auch für C-Programme gelten.

Gruss
Axel

von Sven P. (Gast)


Lesenswert?

Axel schrieb:
> Sven P. schrieb:
>> Axel Laufenberg schrieb:
>> ...
>> Les halt mal Linux-Kernelquellen(1). Keine Sau kommentiert da solche
>> Banalitäten. Obwohl ich von Kernelentwicklung überhaupt keine Ahnung
>> habe, fühle ich mich in den Quellen zurecht und wohl - in weiten Zügen
>> ist der Quelltext problemlos nachvollziehbar.
> Wenn Du das sagst.
Sage ich. Und damit meine ich nicht, dass ich verstehe, was irgendwelche 
Unterroutinen im Quelltext machen oder was in den Datenstrukturen steht. 
Wenn ich das nämlich wissen will, schaue ich in deren Dokumentation 
nach.

Mir drängt sich aber der Verdacht auf, dass wir ungewollt etwas 
aneinander vorbeireden, mal schaun.


>> Und das funktioniert nun schon etliche Jahre mit unzähligen
>> Programmierern, und zwar durchaus echt fähigen Programmierern. Auch
>> Programmierern, die quereinsteigen und/oder nach langer Pause wieder
>> einen Fuß fassen. Und nun bestehst du wirklich auf kommentierte
>> Banalität?!
> Ja, die machen auch nichts anderes. Davon abgesehen ist das Zeugs ja
> alles andere als auf Anhieb Bugfrei, bzw. es hat Jahre gedauert, bis es
> fehlerfrei lief.
Das wäre aber auch nicht schneller oder fehlerfreier gewesen, wenn die 
Entwickler stets dazugeschrieben hätten, was sie denn gerade falsch 
verstanden haben.


>> Und ja, ich bin auch ein Freund von ausführlich und sauber
>> durchkommentierten Schnittstellen. Sowas muss eindeutig und vollständig
>> sein, es darf/sollte keine Unklarheiten wegen 'aber was passiert
>> eigentlich wenn...' offen lassen.
>>
>> (1) http://git.kernel.org/?p=linux/kernel/git/torvalds...
>
> So beim ersten Durchscrollen finde ich da weder sauber dokumentierte
> Schnittstellen noch sonstwelche Kommentare.
Der Link gehört auch nicht dahin, da ging es mir eher um knappe 
Kommentierung. Saubere Schnittstellen findest du eher in irgendwelchen 
API.


>>Und wenn da dann ein Fehler auffält, musst du dir wieder Gedanken
>>machen, ob der Quelltext falsch ist und nicht das macht, was er laut
>>Kommentar machen soll, oder ob der Quelltext verändert wurde und der
>>Kommentar vergessen. Das ist Redundanz... ein Problem, welches man in
>>jeder (relationalen) Datenbank aus genau diesem Grund zu vermeiden
>>versucht. Das nennt man dann Normalisierung.
>
> Durch die Redundanz kann man wesentlich schneller überprüfen, ob der
> Code das tut, was er soll und was sich der Entwickler gedacht hat. Wenn
> es bei der Revision Diskrepanzen gibt, muss das geprüft und behoben
> werden. Das ist kein Nachteil, das ist ein Vorteil, der teure Fehler
> verhindern hilft.
Ob das schneller geht, weiß ich nicht. Wenn es aber schon Kommentare 
braucht, die den Quelltext beschreiben, damit man nachvollziehen kann, 
ob er denn tut, was er soll... Naja, wäre normalerweise ein starkes 
Anzeichen dafür, den Quelltext anders zu formulieren.


> Ziel ist es also nicht, schönen Code abzuliefern, Ziel ist es
> fehlerfreien Code abzuliefern. Die von Dir angeprangerte Redundanz ist
> dafür ein entscheidendes Hilfsmittel.
Ich bezweifle das nach wie vor. Aber das wäre auch der Punkt, an dem ich 
glaube, dass wir aneinander vorbeireden.

Hälst du es für sinnvoll, über jede idiomatisch formuliere For-Schleife 
nochmal drüberzukommentieren, wie oft die durchläuft? Oder jede 
If-Bedingung nochmal im Kommentar zu nachzuerzählen?
Ich jedenfalls nicht. Viel sinnvoller finde ich, zu kommentieren, 
warum die For-Schleife so und so oft ausgeführt wird, sofern das nicht 
unmittelbar ersichtlich ist. Oder zu kommentieren, was ich mit einer 
If-Abfrage denn testen will.

Also etwa so:
1
/* Worker-Threads freigeben */
2
for (int i = 0; i < chain->length; i++)
3
    sem_post(chain->semaphores[i]);
4
5
if (TIMSK & _BV(OCIE1A))
6
    /* A step is currently in progress */
7
    return false;
8
else if (!mod_swapped())
9
    /* The current modulation mask has not taken effect yet */
10
    return false;
11
else
12
    return true;


Aber NICHT so:
1
/* Alle Semaphores in der Kette freigeben */
2
for (int i = 0; i < chain->length; i++)
3
    sem_post(chain->semaphores[i]);
4
5
if (TIMSK & _BV(OCIE1A))
6
    /* OC1A interrupt is enabled */
7
    return false;
8
else if (!mod_swapped())
9
    /* Not swapped yet */
10
    return false;
11
else
12
    return true;
Diese Kommentare sind einfach Stuss. Dass die Semaphores freigegeben 
werden, sehe ich selbst. Steht nämlich im Quelltext. Und dass der 
OC1A-Interrupt da eingeschaltet ist, sehe ich auch. Das nicht ge-swap-pt 
wurde, ist auch offensichtlich. Alle diese Kommentare bringen überhaupt 
keinen Mehrwert.

In der ersten Variante dagegen plappere ich den Quelltext nicht nach, 
sondern schreibe, warum etwas gemacht wird. Das hilft dann auch 
weiter.

von Rolf M. (rmagnus)


Lesenswert?

Axel Laufenberg schrieb:
> Vlad Tepesch schrieb:
>> Axel Laufenberg schrieb:
>>> Zu viel Kommentar ist in Minuten entfernt.
>>
>> und wie lange braucht es, die Synchronität zwischen Code und Kommentar
>> zu validieren, bzw zu bemerken, dass diese längst verloren wurde?
>
> Ich lasse da ja kein Script drüber laufen, welches alle Kommentare
> löscht.
>
> Aber ich habe dann die Wahl, was ich lösche. Das Original habe ich ja
> dann immer noch.

Dann sind die überfüssigen/störenden Kommentare aber nicht "in Minuten 
entfernt".

von Joachim D. (Firma: JDCC) (scheppertreiber)


Lesenswert?

Rolf Magnus schrieb:
> Dann sind die überfüssigen/störenden Kommentare aber nicht "in Minuten
> entfernt".

Och da gibt's bestimmt ein handliches Tool ;)

von Axel (Gast)


Lesenswert?

Sven,

wir liegen glaube ich wirklich nicht so weit auseinander.

Das Problem ist, dass wenn man die Kernel Quellen sieht, diese eher so 
aussehen:
1
for (int i = 0; i < chain->length; i++)
2
    sem_post(chain->semaphores[i]);
3
4
if (TIMSK & _BV(OCIE1A))
5
    return false;
6
else if (!mod_swapped())
7
    return false;
8
else
9
    return true;

Da ist es mir schon lieber, wenn die Leute sowas schreiben:
1
/* Worker-Threads freigeben */
2
for (int i = 0; i < chain->length; i++)
3
    sem_post(chain->semaphores[i]);
4
5
if (TIMSK & _BV(OCIE1A))
6
    /* OC1A interrupt is enabled */
7
    return false;
8
else if (!mod_swapped())
9
    /* The current modulation mask has not taken effect yet */
10
    return false;
11
else
12
    return true;

(Damit Du es nicht durchsuchen musst, letzteres ist eine Mischung aus 
den beiden)
Zwar eine Menge Überflüssiges, aber doch ein paar Körner dabei. Das ist 
allemal besser.

Wobei auch sowas:
1
else if (mod_swapped())    /* Not swapped yet */

für die Fehlersuche ganz praktisch ist, der Fehler springt einem direkt 
ins Auge. Hier natürlich grenzwertig, aber bei komplexeren Algorythmen 
ist es durchaus sinnvoll, sich mal danebenzuschreiben, was man 
eigentlich machen will.

Gruss
Axel

von Axel (Gast)


Lesenswert?

Rolf Magnus schrieb:
> Axel Laufenberg schrieb:
>> Vlad Tepesch schrieb:
>>> Axel Laufenberg schrieb:
>>>> Zu viel Kommentar ist in Minuten entfernt.
>>>
>>> und wie lange braucht es, die Synchronität zwischen Code und Kommentar
>>> zu validieren, bzw zu bemerken, dass diese längst verloren wurde?
>>
>> Ich lasse da ja kein Script drüber laufen, welches alle Kommentare
>> löscht.
>>
>> Aber ich habe dann die Wahl, was ich lösche. Das Original habe ich ja
>> dann immer noch.
>
> Dann sind die überfüssigen/störenden Kommentare aber nicht "in Minuten
> entfernt".

Das stimmt. Aber bei einem Stück Code, was aus irgendeinem Grund 
Probleme macht, ist es allemal einfacher, überflüssige Kommentare, die 
einen stören, zu löschen (also den Code aufzuräumen) als sich fehlende 
Kommentare aus dem Kontext zu erschliessen.

Idealerweise findet man dann so was:
1
else if (mod_swapped())    /* Not swapped yet */

Dann hat man den Fehler nach einer Minute gefunden.

Wie lange hättest Du dann danach gesucht ?
1
else if (mod_swapped())

Gruss
Axel

von Sven P. (Gast)


Lesenswert?

Axel schrieb:
> Idealerweise findet man dann so was:
>
1
> else if (mod_swapped())    /* Not swapped yet */
2
>
>
> Dann hat man den Fehler nach einer Minute gefunden.
Das kann aber auch wieder in die Hose gehen :-]

Beispiel:
1
if (strcmp(string1, string2)) {
2
  puts("Strings sind verschieden");
3
}

von Axel (Gast)


Lesenswert?

Sven P. schrieb:
> Axel schrieb:
>> Idealerweise findet man dann so was:
>>> else if (mod_swapped())    /* Not swapped yet */
>> >
>> Dann hat man den Fehler nach einer Minute gefunden.
> Das kann aber auch wieder in die Hose gehen :-]
>
> Beispiel:if (strcmp(string1, string2)) {
>   puts("Strings sind verschieden");
> }

Verstehe jetzt nicht, was Du damit sagen willst.

Antwort schreiben

Die Angabe einer E-Mail-Adresse ist freiwillig. Wenn Sie automatisch per E-Mail über Antworten auf Ihren Beitrag informiert werden möchten, melden Sie sich bitte an.

Wichtige Regeln - erst lesen, dann posten!

  • Groß- und Kleinschreibung verwenden
  • Längeren Sourcecode nicht im Text einfügen, sondern als Dateianhang

Formatierung (mehr Informationen...)

  • [c]C-Code[/c]
  • [code]Code in anderen Sprachen, ASCII-Zeichnungen[/code]
  • [math]Formel in LaTeX-Syntax[/math]
  • [[Titel]] - Link zu Artikel
  • Verweis auf anderen Beitrag einfügen: Rechtsklick auf Beitragstitel,
    "Adresse kopieren", und in den Text einfügen




Bild automatisch verkleinern, falls nötig
Bitte das JPG-Format nur für Fotos und Scans verwenden!
Zeichnungen und Screenshots im PNG- oder
GIF-Format hochladen. Siehe Bildformate.
Hinweis: der ursprüngliche Beitrag ist mehr als 6 Monate alt.
Bitte hier nur auf die ursprüngliche Frage antworten,
für neue Fragen einen neuen Beitrag erstellen.

Mit dem Abschicken bestätigst du, die Nutzungsbedingungen anzuerkennen.