Sollten wir ausführlich Kommentare schreiben?

Question

Mögliche Duplizieren:
Commenting code

C# ist Hochsprache und in diesen Tagen ich über Code gekommen sind, die weniger Kommentare hat als zu Code verglichen vor ein paar Jahren geschrieben. Sollten wir wirklich einen Code in hohem Maße kommentieren? Ich möchte nur die Gedanken von euch Leuten wissen.

Answer 1

Es gibt ein ganzes Kapitel gewidmet Bemerkungen in Robert C Martins ausgezeichnetes Buch Clean Code.

Einige Highlights:

• Refactoring Bevorzugen über Kommentierung
• Sie die offensichtliche
• Halten Arten und Methoden kurze und konzentrierte sich nicht äußern (SRP)

Answer 2

Ich lebe nach 1 Regel; Kommentiere nicht offensichtlichen Code.

ich auch Code schreibt so offensichtlich wie möglich versuchen, damit ein großer Mangel an Kommentaren in meinem Code :)

Answer 3

Von den älteren Tagen Computing, kommentiere nicht alles, zum Beispiel:

if(a == 3) { // if a equals three, then... 
    cout << "a is three" << endl; // output "a is three" and a newline 
} // otherwise don't print anything 

a++; // increment a 

Kommentare sollten vor allem sinnvoll sein. Es empfiehlt sich, einen Kommentarkopf für jede Funktion oder Klasse anzugeben, aber nicht jede einzelne Zeile zu kommentieren.

Answer 4

Es ist nicht unbedingt die Menge der Kommentare, die Sie wollen, aber die Qualität. Kommentare sollten dem Code Verständnis verleihen.

Answer 5

C# haben beide einen imperativen Codierungsstil (für (jedes), während usw.) und einen deklarativen Stil (LINQ, Abfragen).

Der deklarative Stil ist viel lesbarer und braucht meiner Meinung nach weniger Kommentare. Jeder kann sehen, was dieser Code tun:

var males = from person in persons 
      where person.Gender == Gender.Male 
      select person; 

Aber mit einer for(each) Schleife Version es nicht, dass sichtbar sein kann (für etwas fortgeschrittenere vielleicht) und Kommentare benötigt.

=

Kommentar, wenn der Code für andere klar is'nt (und Sie).

Answer 6

Mein Vorschlag ist, Kommentare in einem nützlichen Schema zu schreiben, so dass die Kommentare von Dokumentation-generierenden Programmen wie Doxygen lesbar sind. Dies wird viel Zeit für das Schreiben von Dokumentationen einsparen.

Answer 7

1.) schreiben Code, der nicht

kommentiert werden müssen

2.), wenn Sie wirklich einen Kommentar muss dies oft ein Code Geruch - vielleicht können Sie etwas ändern, und Sie müssen es nicht kommentieren

Answer 8

ich damit einverstanden :

http://www.codinghorror.com/blog/2008/07/coding-without-comments.html

Answer 9

selbsterklärende Variablen und Methodennamen sind viel wichtiger als Kommentare. Wenn die Namen gut sind und die Architektur einfach zu verstehen ist, sind fast keine Kommentare erforderlich.

Also nur Kommentar Methodenheader und Parameter (für die automatische Generierung der Dokumentation) und innerhalb der Implementierung nur, wenn es ein komplizierter Algorithmus oder Design Pattern (manchmal ein Link zu einem Papier oder Wikipedia ist ausreichend) oder ein "Hack" oder Problemumgehung. Diese komplizierten und "schmutzigen" Teile des Codes versuche ich zu kommentieren sehr ausgiebig, denn das sind die Teile des Codes wo andere (oder Sie nach 6 Monaten) nur "WTF?" Denken, wenn sie das sehen Code - erklären Sie, warum Sie dies getan haben und was getan werden muss, um den Code zu verbessern. (Oft wissen Sie dies bei der Implementierung eines Hacks, aber es ist zu wenig Zeit oder Risiko (und somit Testaufwand) zu hoch).

Answer 10

Setzen Sie Kommentare, die möglicherweise nicht einfach zu sein scheinen. Das bedeutet, dass Sie Kommentare hinzufügen müssen, um zu sagen, welcher Algorithmus Sie verwenden (z. B. während einer Sortiermethode möchten Sie erwähnen, ob Sie Bubble Sort oder Merge sort verwenden) oder in Fällen, in denen Sie Änderungen am ursprünglichen Algorithmus vornehmen eine unsortierte Liste in Gruppen von drei statt zwei, wenn Merge Sort).

Wenn jemand anders, der Ihren Code betrachtet, verwirrt sein kann und ein etwas kompetenter Programmierer ist, werfen Sie einen Kommentar ein, um zu erklären, was Sie tun und warum.

Answer 11

Ein Argument für umfangreiche Kommentare ist, dass wir alle verschiedene Stile und Methoden haben, wenn wir programmieren. Wo ich arbeite, könnten zwei oder drei von uns das gleiche Projekt teilen. Wenn ich eine Woche lang gehackt habe und sie mir ausgehändigt habe, hätten sie keine Ahnung, woher ich komme.

Ich neige dazu, zu kommentieren, wenn ich der Person, die den Code benutzt, etwas erklären muss. Sie wissen, wie man programmiert, sonst würden sie Code nicht ansehen.

//check to see if variable is X 
if ($variable == "x"){ 
    return true; 
}else{ 
    return false; 
} 

Ich würde nicht mit diesen Kommentar über Bord gehen, aber wenn ich glaube, ich habe etwas zu erklären, dann mache ich so

Answer 12

schreiben Kommentare, die erklären, warum Sie etwas tun, nicht wie Du machst es. Der Code sollte klar genug sein, damit andere das Wie verstehen können.

Answer 13

Ja, Kommentare sind sehr nützlich, nicht nur für Sie, sondern auch für andere.