Wann sind Kommentare "zu viel" und wann sind sie nicht genug?

Question

Es gibt eine fortwährende kleine Debatte, in der ich über die Wirksamkeit von Kommentaren innerhalb des Codes arbeite. Einer der Leads wies seine Entwickler an, keine Kommentare zu verwenden, da sie zu "altmodisch" sind, und einige andere Entwickler gaben an, dass sie niemals Kommentare verwenden, da sie nur das Gefühl haben, den Code zu überladen.

Ich habe mich immer ziemlich an die Praxis gehalten, dass ich den Anfang jeder Datei mit einem einfachen Kommentarblock kommentiere, jede Methode/Klasse/etc-Definition kommentiere und dann jeden beliebigen Punkt im Code kommentiert, an den ich denke komm zurück in 6 Monaten und denke mir, "WTF".

Dies ist eindeutig subjektiv, aber ich bin neugierig zu wissen, ob jemand wirklich gute Argumente oder Erfahrungen für die eine oder andere Weise hat.

Answer 1

Dies wurde zu Tode diskutiert.

Ich werde Sie nur auf Jeff Atwood's wonderful post on the subject hinweisen, die den Nagel direkt auf den Kopf trifft.

Answer 2

Hin und wieder laufe ich auf Code, der so elegant partitioniert ist, hat so zwingend offensichtliche Methode, Feld und Variablennamen, dass alles, was ich wissen muss, aus dem Code offensichtlich ist.

Im allgemeinen Fall schreiben nur wirklich großartige Code-Gurus solchen Code. Der Rest von uns steckt etwas zusammen, das funktioniert.

Wenn Sie ein wirklich toller Code-Guru sind, belästigen Sie nicht Ihren göttlichen Code mit überflüssigen Kommentaren.

Wenn Sie kaum wissen, was Sie tun, seien Sie vorsichtig, Ihre Fehlversuche zu dokumentieren, damit andere versuchen können, das Durcheinander zu retten.

Wenn Sie durchschnittlich sind (und die meisten von uns sind, per definitionem), dann lassen Sie einige Hinweise in sich selbst und anderen, um die Wartung zu vereinfachen, aber beleidigen Sie niemanden und verschwenden Speicherplatz durch Dokumentieren Das ist wirklich offensichtlich. Idealerweise sollten Ihre Kommentare Ihren Code auf einer Meta-Ebene beschreiben und nicht angeben, was Sie tun, sondern warum. Wie auch, wenn Sie etwas Ungewöhnliches oder Schwieriges tun.

Answer 3

Das Problem mit Kommentaren ist, dass sie dazu neigen, lange zu bleiben, nachdem der Code, der kommentiert wurde, geändert oder sogar gelöscht wurde.

Als Faustregel würde ich nur öffentliche API und schwer verständliche Algorithmen kommentieren.

Verwenden Sie keine Kommentare, um zu erklären, was Sie getan haben - dafür steht der Code. Verwenden Sie Kommentare, um zu erklären, warum Sie das getan haben.

Answer 4

Man sollte vor dem Code oder vor der Funktion einen Kommentar schreiben, damit man beim nächsten Mal, wenn man die Funktion betrachtet, sofort wissen kann, was der Zweck dieses Codes ist.
Es ist mir oft passiert, dass ich den Code schreibe und dann den Zweck vergessen habe. also mache ich es mir zur Gewohnheit, einen Kommentar vor dem Code zu schreiben.

Answer 5

Was ich in den Kommentaren sehen möchte, ist eine Erklärung, warum eine Methode, die offensichtlich und viel einfacher als die im Code verwendete Methode ist, nicht funktioniert.

Answer 6

In meiner ganzen Karriere bin ich nie auf diese wundervolle Bestie "selbst dokumentierenden Code" gestoßen. Vielleicht hatte ich gerade Pech, aber ich beginne zu vermuten, dass es nicht wirklich existiert.

Answer 7

"Einer der Leads wies seine Entwickler an, keine Kommentare zu verwenden, da sie zu" altmodisch "sind, und ein paar andere Entwickler gaben an, dass sie niemals Kommentare verwenden, da sie nur den Code durcheinander bringen."

Wenn ich je einen Entwickler hörte, mit dem ich so reden würde, würde ich sie korrigieren. Wenn ich nicht den nötigen Rang hätte, um sie zu korrigieren, würde ich den Job verlassen.

Sehr klar geschriebener Code mit guten Bezeichnern - das Zeug wird manchmal als "selbstdokumentierend" bezeichnet - macht einen guten Eindruck, was der Code tut. Soweit ist es in Ordnung. Die Aufgabe der Kommentare ist zu erklären, warum.

Answer 8

Dieses Thema neigt viel diskutiert zu werden, aber hier sind meine US $ 0,02 zum Thema:

1. Ich würde eher zu viele Kommentare sehen, als nicht genug. Wenn Sie nichts erreichen, können Sie immer überflüssige Kommentare aus dem Code löschen. Sie können jedoch keine Bedeutung von ihnen ableiten, wenn es keine gibt.
2. Ich habe gehört, einige Entwickler argumentieren, dass andere Entwickler, die "überdokumentieren" (Definitionen davon variieren von Person) ihren Code sind nicht gute Entwickler. Wenn Sie sagen, dass Sie einen Zähler aktualisieren, kann dies ein Zeichen dafür sein, dass Sie nicht wissen, was Sie tun. Eine klare Anleitung zu einigen der Geschäftslogiken, die sich dort mitten in der Methode befinden, an der Sie arbeiten, kann sehr nützlich sein.
3. Während es einige ausgezeichnete Entwickler gibt, die extrem klaren Code schreiben können, der keine Kommentare erfordert, sind die meisten Entwickler nicht so gut oder verbringen mehr Zeit damit, den Code zu schreiben, um selbstdokumentierend zu sein, als wenn sie nur hätten enthalten ein paar Kommentare.
4. Sie kennen nicht die Fähigkeit der nächsten Person, Ihren Code zu lesen, und wenn die von Ihnen verwendeten Sprachkonstrukte verwirrend sind, ist es normalerweise eine gute Idee, einen Kommentar hinzuzufügen, mit dem jemand ein Tutorial mit Google verwenden kann.

Answer 9

Diomidis Spinellis schrieb gerade eine schöne Säule für IEEE-Säule (quoted on his blog), umreißt das Problem, und ein paar Lösungen:

Wenn kommentieren, sind wir immer ein paar von Tastenanschlägen vor einer Katastrophe entfernt: die Funktion des Codes in wieder auf Englisch. Und das ist, wenn Probleme starten.