Wie gefällt Ihnen Ihre Kommentare? [geschlossen]

Question

Was sind Ihre besten Praktiken für Kommentare? Wenn sie verwendet werden soll, und was sollen sie enthalten? Oder Kommentare sogar notwendig?

Answer 1

Die Kommentare sind wichtig für die Wartbarkeit. Der wichtigste Punkt ist, zu erklären, warum Sie tun etwas, nicht was ist Sie tun.

Answer 2

In der Schule war die Regel alles zu kommentieren, so sehr, dass Kommentare Code aufwiegen. Ich denke, das ist dumm.

Ich denke, Kommentare verwendet werden sollte, das „Warum“ hinter Code zu dokumentieren, nicht das „Wie“ ... der Code selbst das „Wie“ erklärt. Wenn es eine Operation, die nicht wirklich klar, warum ist es geschehen ist, das ist ein guter Ort für einen Kommentar.

Todo und FIXME die manchmal in den Kommentaren gehen, sondern im Idealfall sollten sie im Quellcode-Management und Bug-Tracking-Tools gehen.

Die einzige Ausnahme davon, wo ich nichts dagegen habe, scheinbar nutzlose Kommentare ist für die Dokumentation Generatoren, die nur Druck Dokumentation für Funktionen, die kommentiert werden - in diesem Fall jede öffentliche Klasse und API-Schnittstelle zumindest genug kommentiert werden muss Holen Sie sich die Dokumentation erzeugt.

Answer 3

Im Idealfall kann Ihr Programm mit dem Leser in Code kommunizieren und nicht in den Kommentaren. Die Möglichkeit, Software zu schreiben, die anderen Programmierer können schnell zu verstehen, die besten Programmierer aus dem Durchschnitt meiner Meinung nach trennt. Typischerweise können, wenn Sie oder Ihre Kollegen nicht einen Abschnitt von Code ohne Kommentare verstehen, als dies ein „Codegeruch“ ist und Refactoring, um sein sollte. Allerdings wird es einige archaische Bibliotheken oder andere Integrations, dass ein paar Kommentare der durchschnittliche Entwickler führen ist nicht unbedingt schlecht.

Answer 4

Wie oft ist die Antwort: es hängt davon ab. Ich denke, der Grund, warum Sie einen Kommentar geschrieben haben, ist sehr wichtig für die Entscheidung, ob der Kommentar gut oder schlecht ist. Es gibt mehrere mögliche Gründe für Bemerkungen:

• die Struktur klarer zu machen (das heißt, die Schleife hier beendet)

Bad: Das sieht aus wie ein möglicher Codegeruch. Warum ist der Code so kompliziert, dass es um einen Kommentar muss, dass klären?

• zu erklären, was der Code tut

Sehr schlecht: Das ist meiner Meinung nach gefährlich. Oft wird es passieren, dass Sie später den Code ändern und über den Kommentar vergessen. Jetzt ist der Kommentar falsch. Das ist sehr schlecht.

• , um anzuzeigen, eine Abhilfe / a Bugfix

Gut: Manchmal ist eine Lösung für ein Problem scheint klar zu sein, aber der einfache Ansatz ein Problem hat. Wenn Sie das Problem zu beheben, kann es hilfreich sein, um einen Kommentar zu schreiben, warum dieser Ansatz gewählt wurde. Ansonsten kann später ein anderer Programmierer denken, dass er den Code ‚optimieren‘ und den Fehler wieder einführen. Denken Sie an die Debian-OpenSSL-Problem. Der Debian-Entwickler entfernt, um eine unitialized Variable. Normalerweise eine unitialized Variable ist ein Problem, in diesem Fall ist es für die Zufälligkeit nötig war. Ein Code Kommentar dazu beigetragen hat, würde das klären.

• für Dokumentationszwecke

Gut: können Einige Dokumentation von Sonder formatiert Kommentare erzeugt werden (das heißt Javadoc). Es ist hilfreich, öffentliche APIs zu dokumentieren, das ist ein Muss. Wichtig ist, sich daran zu erinnern, dass die Dokumentation enthält die Absicht des Codes, nicht die Umsetzung. So beantwortet der Kommentar gegen die Frage: ‚Warum Sie die Methode benötigen (und wie verwenden Sie es)‘ oder Was bedeutet die Methode?

Answer 5

Ich denke, die neue Bewegung Kommentare zu entfernen ist schlecht ... der Grund, es gibt eine Menge von Programmierern, die denken, dass sie einfach sind, das Schreiben von Code zu verstehen, die Kommentare nicht braucht. Aber in Wirklichkeit sein einfach nicht der Fall.

Wie viel Prozent der anderen Völker Code tun Sie lesen und sofort verstehen .. Vielleicht lese ich zu viel klassischen Asp, Perl und C ++, aber die meisten Sachen, die ich lesen ist schwierig zu überfliegen.

Haben Sie jemals jemand den Code zu lesen, und wurde durch sie völlig verwirrt. Glauben Sie, dass sie dachten, während sie schreiben, das ist Mist, aber ich weiß nicht wirklich. Sie dachten wahrscheinlich ohh ... das ist sehr klug, und es wird SUPER schnell.

Answer 6

Nur ein paar Bemerkungen:

Kommentare sind wichtig für alles, was nicht leicht aus dem Code (zum Beispiel komplexe mathematische Algorithmen) abgeleitet werden.

Die Probleme mit Kommentaren sind, dass sie benötigen, wie der Code beibehalten werden, aber oft überhaupt nicht beibehalten.

Ich mag es nicht Kommentare wie folgt aus:

// Create the "Analyze" button
Button analyzeButton = new Button();
analyzeButton.Text = "Analyze";
analyzeButton.Location = new Point( 100, 100 );
Controls.Add( analyzeButton );

Besser:

CreateAnalyzeButton();


void CreateAnalyzeButton()
{
    Button analyzeButton = new Button();
    analyzeButton.Text = "Analyze";
    analyzeButton.Location = new Point( 100, 100 );
    Controls.Add( analyzeButton );
}

Nun sagt der Code die ganze Geschichte. Keine Notwendigkeit für einen Kommentar.

Answer 7

Ich denke, es ist auf dem Szenario ab.

Methoden / Funktionen / Klassen müssen eine kurze Beschreibung dessen, was sie tun, wie sie es tun, was sie nehmen und was sie zurückkommen, wenn sie nicht sofort offensichtlich, und dass in der Regel (in meinem Code) kommt in Form eines javadoc- Stil Kommentarblock.

In-Block-Code, neige ich dazu, über einen Block von Zeilen einen Kommentar zu hinterlassen, zu erklären, was es tut, oder man am Ende der Zeile, wenn es ein kurzer und kryptischer Funktionsaufruf.

Answer 8

, um die Tag-Suche verwenden und Sie werden feststellen, SO hat einen Haufen Diskussion über Code-Kommentare schon:

https://stackoverflow.com/questions/tagged/comments

kommentierte Code

Answer 9

Hier finden Sie aktuelle Code Complete . Es ist einfach am besten für solche Themen.