Ich habe die anderen Fragen gesehen , aber ich bin immer noch nicht zufrieden mit der Art, wie dieses Thema behandelt wird .
Ich möchte eine Liste mit Dingen extrahieren, die bei einer Code-Überprüfung auf Kommentare überprüft werden.
Ich bin mir sicher, dass die Leute Dinge sagen werden, die sich gegenseitig aufheben. Aber hey, vielleicht können wir für jedes Camp eine Liste erstellen. Für diejenigen, die nicht kommentieren, wird die Liste nur sehr kurz sein:)
Ich habe eine einfache Regel zum Kommentieren: Dein Code sollte die Geschichte von dem erzählen, was du tust; Ihre Kommentare sollten die Geschichte erzählen, warum Sie es tun.
Auf diese Weise stelle ich sicher, dass derjenige, der meinen Code erbt, in der Lage ist, die Absicht hinter dem Code zu verstehen.
Wenn ein Kommentar veraltet ist (nicht mit dem Code übereinstimmt), löschen Sie ihn oder aktualisieren Sie ihn. Lassen Sie niemals einen ungenauen Kommentar an Ort und Stelle.
Schreibe einen lesbaren Code, der so gut wie möglich selbsterklärend ist. Fügen Sie Kommentare hinzu, wenn Sie Code schreiben müssen, der zu komplex ist, um ihn auf einen Blick zu verstehen. Fügen Sie auch Kommentare hinzu, um den Geschäftszweck hinter dem Code zu beschreiben, den Sie schreiben, um die Pflege in Zukunft einfacher zu gestalten.
Dokumentation ist wie Sex; wenn es gut, es ist sehr, sehr gut und wann es ist schlecht, es ist besser als nichts
Wenn Sie eine RFC oder eine andere Protokollspezifikation implementieren, kommentieren Sie State Machines / Event Handler / etc mit dem Abschnitt der Spezifikation, dem sie entsprechen. Stellen Sie sicher, dass Sie die Version oder das Datum der Spezifikation auflisten, falls sie später überarbeitet wird.
Die Kommentare, die Sie schreiben, können über die Qualität Ihres Codes aufschlussreich sein. Unzählige Male habe ich Kommentare in meinem Code entfernt, um sie durch besseren, klareren Code zu ersetzen. Dazu folge ich ein paar Anti-Kommentar-Regeln:
Das sind wirklich die gleichen Regeln, die für zwei verschiedene Kontexte wiederholt werden.
Die anderen, normaleren Regeln, denen ich folge, sind:
Normalerweise kommentiere ich eine Methode, bevor ich sie schreibe. Ich schreibe ein oder zwei Kommentare für jeden Schritt, den ich innerhalb der Funktion ausführen muss, und schreibe dann den Code zwischen den Kommentaren. Wenn ich fertig bin, ist der Code bereits kommentiert.
Das Tolle daran ist, dass es kommentiert wurde, bevor ich den Code schreibe, also gibt es keine unangemessenen Annahmen über das vorherige Wissen in den Kommentaren; Ich selbst wusste nichts über meinen Code, als ich sie schrieb. Dies bedeutet, dass sie leicht zu verstehen sind, so wie sie sein sollten.
Es gibt keine harten Regeln - harte Regeln führen zu Dogmen und Menschen folgen im Allgemeinen Dogmen, wenn sie nicht schlau genug sind, selbst zu denken.
Die Richtlinien Ich folge:
1 / Kommentare sagen, was gemacht wird, Code sagt, wie es gemacht wird - dupliziere deine Bemühungen nicht.
2 / Kommentare sollten sich auf Code-Blöcke beziehen, nicht auf jede Zeile. Dazu gehören Kommentare, die ganze Dateien, ganze Funktionen oder nur einen komplizierten Codeschnipsel erklären.
3 / Wenn ich denke, dass ich in einem Jahr zurückkommen und die Code / Kommentar-Kombination nicht verstehen würde, sind meine Kommentare noch nicht gut genug.
Eine großartige Regel für Kommentare: Wenn Sie Code durchlesen, der versucht, etwas herauszufinden, und ein Kommentar irgendwo Ihnen die Antwort gegeben hätte, setzen Sie es dort, wenn Sie die Antwort kennen .
Verbringe die Zeit nur damit, einmal zu untersuchen .
Schließlich wirst du wissen, während du schreibst die Orte, an denen du die Führung verlassen musst, und die Orte, die ausreichend offensichtlich sind, um alleine zu stehen. Bis dahin wirst du Zeit damit verbringen, deinen Code zu durchsuchen, um herauszufinden, warum du etwas getan hast:)
Ich dokumentiere jede Klasse, jede Funktion, jede Variable innerhalb einer Klasse. Einfache DocBlocks sind der Weg nach vorn.
Ich schreibe diese Docblocks im Allgemeinen mehr für automatisierte API-Dokumentation als alles andere ...
Zum Beispiel der erste Abschnitt einer meiner PHP-Klassen
%Vor%Aber dann dokumentiere ich manchmal auch wichtigen Code (aus meiner init.php
) %Vor%Und wenn es nicht selbsterklärend ist, warum etwas auf eine bestimmte Weise etwas tut, werde ich das kommentieren
Ich erstelle am Anfang meines Codes einen Kommentarblock, der den Zweck des Programms, das Datum der Erstellung, alle Lizenz- / Copyright-Informationen (wie GPL) und den Versionsverlauf auflistet.
Ich sage oft zu meinen Importen, wenn es nicht offensichtlich ist, warum sie importiert werden, vor allem, wenn das gesamte Programm anscheinend keine Importe benötigt.
Ich füge jeder Klasse, Methode oder Funktion einen Docstring hinzu und beschreibe, was der Zweck dieses Blocks ist und welche zusätzlichen Informationen ich für notwendig halte.
Ich habe normalerweise eine Demarkationslinie für Abschnitte, die verwandt sind, z. Widget-Erstellung, Variablen usw. Da ich SPE für meine Programmierumgebung verwende, werden diese Abschnitte automatisch hervorgehoben und die Navigation erleichtert.
Ich füge TODO-Kommentare während der Codierung als Erinnerungen hinzu. Es ist eine gute Möglichkeit, mich selbst daran zu erinnern, den Code zu refaktorieren, wenn er einmal korrekt funktioniert.
Abschließend möchte ich einzelne Zeilen kommentieren, die eine Klärung erfordern oder anderweitig einige Metadaten für mich selbst in der Zukunft oder andere Programmierer benötigen.
Ich persönlich hasse es, Code zu betrachten und herauszufinden, was er tun soll. Wenn jemand einfach einen einfachen Satz schreiben könnte, um das zu erklären, ist das Leben einfacher. Selbstdokumentierender Code ist in meinem Buch eine falsche Bezeichnung.
Ich konzentriere mich auf warum . Denn das was ist oft gut lesbar. TODOs sind auch großartig, sie sparen viel Zeit.
Und ich dokumentiere Schnittstellen (zum Beispiel Dateiformate).
Wenn Sie Kommentare schreiben, halten Sie inne, reflektieren Sie und fragen Sie sich, ob Sie den Code ändern können, damit die Kommentare nicht benötigt werden. Könnten Sie einige Variablen-, Klassen- oder Methodennamen ändern, um die Dinge klarer zu machen? Würden einige assert s oder andere Fehlerprüfungen Ihre Absichten oder Erwartungen kodifizieren? Könnten Sie einige lange Codeabschnitte in klar benannte Methoden oder Funktionen aufteilen? Kommentare spiegeln oft unsere Unfähigkeit wider, klar zu schreiben (a-hem, code). Es ist nicht immer einfach, mit Computersprachen klar zu schreiben, aber nehmen Sie sich etwas Zeit, um es zu versuchen ... weil Code niemals lügt.
P.S. Die Tatsache, dass Sie Zitate um "harte Regeln" verwenden, sagt es. Regeln, die nicht erzwungen werden, sind keine "harten Regeln" und die einzigen Regeln, die erzwungen werden, sind im Code.
Ich füge einen Kommentar zu einem Code-Block hinzu, der fasst, was ich gerade mache. Dies hilft Menschen, die nach einer bestimmten Funktionalität oder einem bestimmten Codeabschnitt suchen.
Ich erkläre jeden komplexen Algorithmus oder Prozess, der auf den ersten Blick nicht verstanden werden kann.
Ich unterschreibe meinen Code.
Meiner Meinung nach sind TODO / TBD / FIXME usw. in Code, an dem gerade gearbeitet wird, in Ordnung, aber wenn Sie Code sehen, der in 5 Jahren nicht berührt wurde und voll davon ist, dann erkennen Sie das es ist eine ziemlich miese Art, dafür zu sorgen, dass die Dinge repariert werden. Kurz gesagt,
Hudson (CI-Server) hat ein großartiges Plugin, das nach TODOs sucht und feststellt, wie viele es in Ihrem Code gibt. Sie können sogar Schwellenwerte setzen, die dazu führen, dass der Build als instabil klassifiziert wird, wenn zu viele davon vorhanden sind.
Meine Lieblingsfaustregel zu Kommentaren lautet: Wenn der Code und die Kommentare nicht übereinstimmen, sind beide wahrscheinlich falsch
Eine wirklich wichtige Sache, nach der Sie beim Überprüfen der Header-Dokumentation (oder wie immer Sie den Block vor der Methodendeklaration aufrufen) suchen, ist, dass Anweisungen und Vorbehalte leicht zu erkennen sind.
Direktiven sind Anweisungen, die den Client betreffen: nicht vom UInthread aufrufen, nicht im leistungskritischen Code verwenden, X vor Y aufrufen, Rückgabewert nach der Verwendung freigeben , usw.
Vorbehalte sind alles, was eine böse Überraschung sein könnte: verbleibende Aktionselemente, bekannte Annahmen und Einschränkungen usw.
Wenn Sie sich auf eine Methode konzentrieren, die Sie schreiben und untersuchen, sehen Sie alles. Wenn ein Programmierer Ihre Methode und dreißig andere in einer Stunde verwendet, können Sie sich nicht auf ein gründliches Lesen verlassen. Ich kann Ihnen Forschungsdaten senden, wenn Sie interessiert sind.
Wir haben einen Artikel über Kommentare geschrieben (eigentlich habe ich mehrere davon gemacht): Ссылка
Es ist wirklich einfach: Kommentare werden geschrieben, um Ihnen zu sagen, was der Code nicht kann.
Dies führt zu einem einfachen Prozess: - Schreiben Sie einen beliebigen Kommentar auf den ersten. - Verbessere den Code, damit der Kommentar überflüssig wird - Löschen Sie den jetzt redundanten Kommentar. - Nur Code, der keine redundanten Kommentare enthält, committen
Tags und Links coding-style comments code-comments