Codierungsstandard für Klarheit: Jede Codezeile kommentieren?

142

Ich habe in Geschäften gearbeitet, die lebenswichtige Software herstellen, und habe mich mit Kommentierungsregeln befasst, die den Code lesbar halten und möglicherweise Leben retten sollten. Meiner Erfahrung nach ist die Anforderung, von einer Checkliste gestrichen zu werden, hirnschmerzhaft und hilft mir nicht, mich darauf zu konzentrieren, verständlichen Code zu schreiben. Dies lenkt meinen Peer-Reviewer auch davon ab, mit mir eine aussagekräftigere Konversation darüber zu führen, wie der Code besser verständlich gemacht werden kann.

Ich habe auch Studentencode benotet, der keine Kommentare hatte, und habe gesehen, warum sie für das Vernachlässigen mit einem Vermerk versehen werden sollten.

Ich verstehe, dass gute Namen, einfache Strukturen, kurze Funktionen und fokussierte Module den Code so verständlich machen, dass Kommentare minimiert werden können.

Ich verstehe auch, dass Kommentare erklären sollten, warum der Code das tut, was er tut, nicht wie.

Ist es angesichts all dessen überhaupt möglich, gute Codierungsstandards zu schreiben, die diese Idee aufgreifen? Personen, die für eine Begutachtung relevant sind, sich jedoch nicht in eine sinnlose Checklistenaktivität verwandeln, die Notizen erstellt, die nicht hilfreicher sind als: "Sie haben vergessen, in Zeile 42 einen Kommentar abzugeben".

Ein Beispiel für die Art von Code, die diese Regel möglicherweise benötigt, wenn sie als Zeile in einer Checkliste behandelt wird:

/* Display an error message */
function display_error_message( $error_message )
{
    /* Display the error message */
    echo $error_message;

    /* Exit the application */
    exit();
}

/* -------------------------------------------------------------------- */

/* Check if the configuration file does not exist, then display an error */
/* message */
if ( !file_exists( 'C:/xampp/htdocs/essentials/configuration.ini' ) ) {
    /* Display an error message */
    display_error_message( 'Error: Configuration file not found. Application has stopped');
}

Wenn es möglich ist, dies in einem Standarddokument richtig auszudrücken, und dies möglicherweise nicht, möchte ich eine Idee in dieser Richtung erfassen:

Betrachten Sie einen Kommentar für jede Zeile, Sequenz, Anweisung, Sektion, Struktur, Funktion, Methode, Klasse, Paket, Komponente, ... des Codes. Als nächstes sollten Sie überlegen, ob Sie diesen Kommentar umbenennen und vereinfachen müssen, um ihn zu löschen. Checken Sie ein, während Kommentare selten sind. Wiederholen Sie bis zum Abgabetermin. Dann noch etwas wiederholen

kandierte_orange
quelle
21
Kommentare sind nicht für eine längere Diskussion gedacht. Diese Unterhaltung wurde in den Chat verschoben .
maple_shaft
32
"Kommentare sind nicht für längere Diskussionen gedacht" gilt umso mehr für Codekommentare. :) Diese /* Display an error message */Kommentare sind schrecklich und wirken sich tatsächlich auf die Lesbarkeit aus.
Andrea Lazzarotto
Wir brauchen unsere IDEs, um Optionen zum Ausblenden von Kommentaren zu haben. Möglicherweise eine Option für Block- und Inline-Kommentare, die separat ausgeblendet werden. Auf diese Weise haben Sie das Beste aus beiden Möglichkeiten. Fügen Sie viele Kommentare ein, aber Sie können sie ausblenden, um den Code übersichtlich und übersichtlich zu halten.
Doug.McFarlane
1
@ Doug.McFarlane Ich dachte das sollte für vim existieren. Natürlich sowohl auf Datei- als auch auf Blockebene - rtfm-sarl.ch/articles/hide-comments.html !
Michael Durrant
1
Also toggling - stackoverflow.com/a/11842371/631619
Michael Durrant

Antworten:

171

Die Antwort von Michael Durrant ist meiner Meinung nach nicht schlecht, aber sie beantwortet die Frage nicht buchstäblich (wie er selbst zugab), also werde ich versuchen, eine Antwort zu geben, die Folgendes bewirkt:

Ich verstehe auch, dass Kommentare erklären sollten, warum der Code das tut, was er tut, nicht wie.

Ist es angesichts all dessen überhaupt möglich, gute Codierungsstandards zu schreiben, die diese Idee aufgreifen?

Natürlich können Sie eine Checkliste für Ihre Code-Überprüfungen schreiben , die Fragen wie enthält

  • "Wenn es einen Kommentar gibt, erklärt er, warum der Code das tut, was er tut?"
  • "Ist jede Codezeile - in ihrem Kontext - entweder selbsterklärend genug, dass sie keinen Kommentar benötigt, oder, falls nicht, wird sie von einem Kommentar begleitet, der diese Lücke schließt? Oder kann der Code (vorzugsweise) so geändert werden braucht es keinen kommentar mehr? "

Wenn Sie möchten, können Sie dies als "Codierungsstandard" bezeichnen (oder nicht, wenn Sie der Meinung sind, dass der Begriff Codierungsstandard für eine Liste von Braindead-Regeln reserviert sein sollte, die einfach zu beantworten sind, ob sie erfüllt sind oder nicht, wie die Formatierung des Codes sollte aussehen oder wo Variablen deklariert werden sollen). Niemand hindert Sie daran, sich auf semantische Fragen zu konzentrieren, anstatt den einfachen Weg zu beschreiten und nur formale Regeln einzuhalten.

Am Ende des Tages sollten Sie sicher sein, dass Ihr Team eine solche Checkliste benötigt. Um solche Fragen anwenden zu können, benötigen Sie Programmierer mit Erfahrung als Prüfer, und Sie müssen herausfinden, ob dies die Lesbarkeit des Codes in einem Expertenteam wirklich verbessert. Aber das müssen Sie gemeinsam mit Ihrem Team ausarbeiten.

Doc Brown
quelle
45
Wer hat das abgelehnt? Dies ist die Antwort für die kritische Softwareentwicklung. Dies ist eine andere Welt im Vergleich zu der, in der die meisten Programmierer arbeiten. In diesen Welten ist ein Kodierungsstandard, der verlangt, dass jede einzelne Codezeile einen eigenen Kommentar enthält, nicht die richtige Antwort. Auch auf Kommentare wird nicht verzichtet. OTOH, Kommentare einer Codeüberprüfung zu unterziehen, ist genau der richtige Standard für kritische Software. Es sorgt für mehr überprüfbaren und wartbaren Code, aber dies ist mit Kosten verbunden. Das kostet weniger als eine Million Dollar, die aus schlecht geschriebener Software resultiert.
David Hammen
4
weise Antwort. Wenn wir echte Regeln für die Codierung finden könnten, bräuchten wir keine Programmierer. Wir könnten einfach den Maschinencode haben. es könnte passieren! :(
4
@DavidHammen: danke für deinen Kommentar. Eigentlich denke ich, dass dies nicht nur für "kritische Softwareentwicklung" gilt. Jede Stücksoftware, die über Jahre hinweg gewartet und weiterentwickelt wurde, oft von unterschiedlichen Personen, wird davon profitieren, dass sie für den nächsten Wartungsprogrammierer verständlich wird.
Doc Brown
5
Dies ist ein guter Rat für jede Codierung, nicht nur für Code, der von verschiedenen Personen gepflegt wird. Selbst wenn Sie der einzige sind, der ein Skript / Programm verwendet, wird die Zukunft, in der Sie den Code in einem Jahr ändern müssen, die Klarheit (und die Zeitersparnis, die dadurch entsteht, dass Sie keinen undurchsichtigen Code entschlüsseln müssen) zu schätzen wissen.
Anthony Geoghegan
5
Könnten Sie die "derzeit am besten bewertete Antwort" auf etwas objektiveres bearbeiten? Nicht jeder Leser wird die Abstimmungshistorie dieser Antworten kennen.
candied_orange
151

Größeres Anti-Pattern führt zu schlechtem Code mit geringerer Klarheit

Übrigens lautete der Titel ursprünglich "Kommentar zu jeder Codezeile?" und Sie können sich vorstellen, wie viele von uns instinktiv reagieren, auch ich. Ich habe später auf den längeren, genaueren Titel zurückgegriffen.

Als ich Ihre Frage gelesen habe, dachte ich, Sie haben sich in Kommentaren verdoppelt, aber ok, vielleicht, wenn Sie genug Einschränkungen für die Bewertungen durch mehrere Personen haben ... aber andererseits: Die Leute machen Fehler, bemerken keine Inkonsistenzen usw. und im Laufe der Zeit es wird am Ende Unterschiede geben. Nachdenken finde ich, dass das Problem viel größer ist:

Entwickler neigen dazu, schlechteren Code zu schreiben. Sie werden mehr kryptische Namen und Strukturen verwenden, weil 'es im Kommentar erklärt wird - siehe!'.

Erwägen:

living_room_set = tables + chairs.

Betrachten wir nun:

set = tbls+chrs # Make the set equal to the table plus the chairs

Sie haben nicht nur mehr kryptische Namen und mehr zu lesen, Sie müssen auch hin und her schauen, sich den Code ansehen, was ist eine Menge? schau nach links auf code, schau nach rechts auf kommentare, was sind tbls, schau nach links auf code, schau nach rechts auf kommentare, was sind chrs, schau nach rechts auf kommentare. Yuch!

Zusammenfassung

Entwickeln oder verbessern Sie einen Kommentar-Standard, wenn Sie gezwungen sind, in Ihrer aktuellen Position als Entwickler (Als ehemaliges COBOL-Programm habe ich sicher große gesehen!), Aber so viel Zeit, Energie und Leidenschaft wie möglich damit zu verbringen, sich gegen die Kommentare zu wehren. Muster mit den Argumenten:

  • Code und Kommentare werden nicht miteinander synchronisiert, wenn nur einer geändert wird

  • Kommentare können beschreiben, was eine Person denkt, aber sie können falsch sein und so Fehler vertuschen

  • Code wird schwerer zu lesen

  • Guter Code wird schwerer zu schreiben

  • Tendenz, eher kryptische Namen zu verwenden

  • Zu viele Zeichen zum Einlesen von Code und Kommentaren

  • Verschiedene Editoren verwenden unterschiedliche Stile

  • Erfordert höhere Englischkenntnisse als nur Codierung

  • Nimmt Zeit und Ressourcen in Anspruch und zieht vom langfristigen Wert ab *

Außerdem sollten Sie sich für einen besseren Code ohne solche Kommentare aussprechen - haben Sie tatsächlich einen Standard (!) - alle Variablennamen müssen vollständige_deutsche_Wörter sein - es gibt einen! Verwenden Sie diese "Standard" -Energie für die Standards gut geschriebener Codes und Tests.

Eines der beiden Hauptprobleme ist das Benennen von Dingen - überspringen Sie das Problem nicht mit Kommentaren.

Da eines der anderen Probleme eine vorzeitige Optimierung ist und die Optimierung im Allgemeinen dazu führen kann, dass der Grund für diesen Code unklar bleibt, sind in diesem Bereich möglicherweise erklärende Kommentare für scheinbar schlechten Code hilfreich, obwohl die obigen Einschränkungen weiterhin gelten.

* Code von morgen

Michael Durrant
quelle
8
Ich glaube nicht, dass du die Frage beantwortet hast. Bei der Frage geht es nicht darum, Kommentare zu jeder Zeile zu haben. Es wird gefragt, wie Entwickler angewiesen werden sollen, Code zu kommentieren, ohne dass sie jede Zeile kommentieren müssen.
Hichris123
7
Ja, ich beantworte nicht die spezifische Frage nach den Standards, sondern versuche den Leuten zu helfen, diesen Weg nicht zu beschreiten. Dies ist also möglicherweise nicht die Antwort auf die spezifische Frage , enthält jedoch wertvolle Ratschläge, die in einem Kommentar nur schwer darzustellen sind.
Michael Durrant
1
Was ist das andere schwierige Problem?
David Grinberg
20
@DavidGrinberg Cache-Ungültigkeit und Fehler nach dem anderen .
Eric King
1
Gegen jeden Ihrer Gründe, Kommentare zu vermeiden, kann vorgegangen werden, aber StackExchange lässt nicht genügend Kommentare zu (heh), damit ich sie alle hier ansprechen kann. Einfach: Überkommentierung ist wie Wahlbetrug: Es kommt vor, aber sehr selten. Wann haben Sie das letzte Mal gesehen, dass es passiert ist? Das Schreiben guter Kommentare sollte nicht nur ein nachträglicher Gedanke sein. Wenn es richtig gemacht wird, hilft es dem Entwicklungsprozess. Ja, es erfordert Ressourcen, aber die Auszahlung ist ein besserer Code. Sie werden nie in der Lage sein, den gleichen Knall für Ihr Geld zu bekommen, indem Sie Kommentare für einen besseren Benennungsstandard für Variablen opfern. Ja, jede Zeile zu kommentieren ist verrückt.
kmoser
23

Ich glaube nicht, dass ein Kodierungsstandard-Dokument der Ort ist, an dem angegeben wird, was bereits vernünftig ist. Der Zweck eines Kodierungsstandards besteht darin, die Konsistenz (und das Vermeiden von Streitigkeiten) bei Fragen zu gewährleisten, bei denen vernünftige Personen möglicherweise nicht zustimmen, und es keine eindeutige richtige Antwort gibt, z. B. Namenskonventionen, Einrückungen usw.

Solche Kommentare wie in Ihrem Beispiel sind objektiv nutzlos und können von einem unerfahrenen Entwickler oder einem Entwickler stammen, der mit einem Build-System gearbeitet hat, das das Vorhandensein von Kommentaren mechanisch überprüft (eine wirklich schlechte Idee, die es jedoch gibt). In beiden Fällen ist die Lösung die Aufklärung, möglicherweise durch Codeüberprüfungen.

Wenn Sie anfangen, alle Arten von "Best Practices" zum Kodierungsstandard hinzuzufügen, werden Sie am Ende nur das wiederholen, was bereits in mehreren Büchern angegeben ist. Kaufen Sie dem betreffenden Entwickler einfach "Clean Code", "Code Complete" und "The Pragmatic Programmer" und halten Sie Ihren Codierungsstandard schlank.

JacquesB
quelle
63
Eines der vielen Dinge, die ich nach über 40 Jahren in diesem Schläger gelernt habe, ist, dass gesunder Menschenverstand überhaupt nicht verbreitet ist.
John R. Strohm
10
Es gibt keinen gesunden Menschenverstand.
Whatsisname
1
in_programming nein .. reale Welt oh yeah, aber es ist nur ein Begriff für reale Welt erfahrenes Wissen
Michael Durrant
@ JohnR.Strohm: Meine Erfahrung war viel positiver als Ihre, aber ich habe auch gesehen, wie der Gebrauch von gesundem Menschenverstand durch die mechanische Durchsetzung von Regeln aktiv entmutigt werden kann.
JacquesB
Ich bin mit dieser Antwort zu 99,9% einverstanden. Der Coding Standard ist das, worauf Entwickler hinweisen, wenn eine Debatte bei Code Review stattfindet. Die Überprüfung von Codes soll das Produkt bereichern und nicht zu Kriegen führen. So viele Kriege, die ich durch Code Reviews ohne Coding Standard ausgelöst habe. Ich wage zu sagen, dass, wenn Sie die Überprüfung der Elemente in der Codierungsnorm nicht automatisieren können, es dort sein sollte. Eine Codeüberprüfung ist die Zeit, um anderen weniger erfahrenen Entwicklern den gesunden Menschenverstand zu vermitteln. Es ist nicht die Zeit, um die Benennung von Variablen zu streiten. linux / kernel / gen_init_cpio.c zeile 335.
Andrew T Finnell
19

Es ist nicht möglich. Was Sie im Wesentlichen versuchen, ist fast, gutes Urteilsvermögen zu mechanisieren.

Beim Schreiben kritischer Software, beispielsweise für lebenserhaltende medizinische Systeme, sind eine Vielzahl von Checklisten und so weiter praktisch unvermeidlich. Nicht nur, dass auch clevere Leute Fehler machen, ein Großteil der Software für diese Geräte wurde von Leuten geschrieben, die nicht sehr gut in ihrer Arbeit sind, daher muss das "System" in der Lage sein, sich vor schlampiger Arbeit zu schützen, um sie sicher zu machen die Kosten der Marktfähigkeit.

Ihre beste Option ist es, den strengen Kodierungsstandard für Kommentare wegzulassen und das Team mit gutem Beispiel voran zu bringen. Zeigen Sie anderen, wie gute Kommentare aussehen, indem Sie sich bemühen, einen qualitativ hochwertigen Code zu erstellen, der entsprechend kommentiert ist. Anstatt zu versuchen, die ultimative Methode zu finden, um zu beschreiben, wie Kommentare geschrieben werden (die selbst häufig ein Urteil sind), zeigen Sie den anderen täglich mit Ihren eigenen Code-Überprüfungen, was Sie meinen. Wenn die anderen Mitglieder Ihren Code lesen, werden sie nachziehen, wenn sie dies für nützlich halten. Und wenn sie das nicht können, hilft ihnen kein Standard dabei, zunächst bessere Kommentare zu schreiben.

Whatsisname
quelle
1
+1 für "Sie versuchen, ein gutes Urteilsvermögen zu erreichen", -1 für "Sie können nur auf das Beste hoffen", und das lässt mich nicht abstimmen. Die Ausbildung und Schulung Ihres Teams ist ebenfalls eine Option. Normen können ein Urteil ermöglichen.
Wildcard
1
@Wildcard Könntest du vielleicht erklären, wie ein Standard ein Urteil ermöglichen kann? Wäre das nicht ein Leitfaden zu diesem Zeitpunkt? Ein Standard ist "eine Idee oder eine Sache, die als Maß, Norm oder Modell in vergleichenden Bewertungen verwendet wird." Wie kann man etwas von Natur aus Subjektives, also Subjektives als Maß für die Qualität verwenden, das davon abhängt, wer es liest?
Andrew T Finnell
1
@Wildcard: Das Problem ist, dass beim Eintritt in regulierte Branchen der Prozess über alles herrscht. Ein Prozess ist wichtiger als die Frage, ob sich der Prozess lohnt oder nicht. Alles muss sich auf Kontrollkästchen in irgendeiner Form beschränken, jedes Kontrollkästchen muss spezifisch und überprüfbar sein, und je mehr Spielraum Sie in einem Kontrollkästchen haben, desto größer ist das Risiko, dass Sie bei einem Audit Probleme bekommen.
Whatsisname
Es ist eine seltsame Welt, und denken Sie daran, dass die Regeln von Bürokraten geschrieben werden, die wenig über die Software-Domäne wissen. Oft haben Sie Systeme, die existieren, um sich selbst zu rechtfertigen und zu fordern, anstatt Mittel zum Zweck zu sein, um Qualitätsprodukte sicherzustellen.
Whatsisname
1
@whatsisname Ich bin sehr froh, dass es noch jemanden gibt, der das versteht. Ihre Antworten sind eleganter und präziser geschrieben, als ich es jemals hätte anstreben können. Die Aussage with systems that exist to justify and require themselves rather than being a means to an end to ensure quality productsist genau das, was ich zu veranschaulichen versuchte. Danke, dass du meine Worte für mich gefunden hast. Ich meine es wirklich so. Wir müssen die Idee, Qualität zu induzieren, von der Idee, einem Prozess zu folgen, trennen, da sie nicht gleich sind. Deshalb haben wir QS, Stackoverflow und sehr verzeihende Kunden.
Andrew T Finnell
14

Aktualisieren

Meine Antwort in Anführungszeichen zur Hervorhebung:

Meiner Meinung nach ist die Antwort, die besagt, dass die Kommentare nicht in den Kodierungsstandards behandelt werden sollten und dann eine Reihe von Abwehrfragen auflistet, die die einzig richtige Antwort sind.

Das Problem hierbei ist, dass ein Kodierungsstandard genau das ist, ein Standard . Extrem subjektive Ideen sollten nicht in einem Kodierungsstandard enthalten sein . Es kann sich um einen Best Practices-Leitfaden handeln, der jedoch während der Codeüberprüfung nicht gegen Entwickler verwendet werden kann. Meiner persönlichen Meinung nach sollte ein Coding Standard so nah wie möglich an Automated sein. Code Reviews verschwenden so viel Zeit damit, über Namen, Abstände, Tabulatoren, Klammern, Kommentare usw. zu streiten, wenn ALLES automatisiert werden kann. Auch die Beantwortung von tablesund chairskann automatisiert werden. LINT'er ermöglichen Wörterbücher, Großschreibungschecks pro Konzept (Variable, Funktion, Methode, Klasse usw.).

Sogar die JavaDoc-Prüfung kann von einem Robot LINT'er implementiert werden, bevor eine Pull-Anforderung akzeptiert wird. Viele Open Source-Projekte machen genau das. Wenn Sie Ihre Pull-Anfrage einreichen, wird der Code mit einer Travis-CI-Datei einschließlich statischer Analyse erstellt und muss alle Codierungsstandards erfüllen, die objektiv ausgedrückt werden können. Kein menschliches Glockenspiel, wenn es darum geht, "es falsch zu machen" oder "keinen Wert" mit einem Kommentar zu versehen oder Variablen falsch zu benennen. Diese Diskussionen haben keinen Wert und werden am besten einem Drittanbieter-Roboter überlassen, der die Hauptlast unserer emotionalen Kodierung übernehmen kann.

Um die Frage tatsächlich zu beantworten, müssten wir uns mit dem Schreiben eines Standards befassen, in dem die folgende Frage beantwortet wird: Hat dieser Kommentar einen Wert geliefert? Ein Kodierungsstandard kann unmöglich den 'Wert' eines Kommentars vorgeben. Daher muss ein Mensch diese Checkliste durchgehen. Die bloße Erwähnung von Kommentaren in einem Kodierungsstandard erzeugt eine Checkliste, die das Originalposter vermeiden möchte.

Das ist der Grund, warum Kommentare normalerweise nicht vom Compiler verarbeitet und entfernt werden. Ihr Wert kann nicht bestimmt werden. Ist der betreffende Kommentar wertvoll? ja oder Nein?. Die Beantwortung dieser Frage ist NP-schwer. Nur Menschen haben die Chance, richtig darauf zu antworten, und selbst dann kann es nur zum Zeitpunkt des Lesens von der Person beantwortet werden, die es liest. Wobei der Wert dieses Kommentars vom Wetter, seinem Leben zu Hause, der letzten Sitzung, an der sie teilgenommen haben, und der Tageszeit und der Menge an Kaffee, die sie getrunken haben, abhängt. Ich vertraue darauf, dass das Bild klarer wird.

Wie kann es jemals in einem Standard richtig ausgedrückt werden? Ein Standard ist nur dann nützlich, wenn er konsequent und fair angewendet werden kann, wenn es bei Fairness eher um Objektivität geht, nicht um Emotionalität.

Ich wetteifere darum, dass ein Kodierungsstandard so objektiv wie möglich bleibt. Die Art und Weise, wie Variablen IS-Ziel genannt werden. Sie können leicht mit einem Wörterbuch verglichen werden, um Rechtschreibung, grammatikalische Struktur und Schreibweise zu überprüfen. Alles, was darüber hinausgeht, ist ein "Pissing Match", das von der Person mit der größten Kraft oder durch "Brauen schlagen" gewonnen wird. Etwas, mit dem ich persönlich Probleme habe, es NICHT zu tun.

Wenn ich kommentiere, spreche ich immer mit meinem zukünftigen Selbst in der dritten Person. Wenn ich in 5 Jahren auf diesen Code zurückkomme, was muss ich dann wissen? Was wäre hilfreich, was wäre verwirrend und was wäre mit dem Code veraltet? Es gibt einen Unterschied zwischen dem Dokumentieren von Code zum Generieren einer durchsuchbaren öffentlichen API und dem Kommentieren von Code, der einem unbekannten Drittanbieter einen Wert liefert, selbst wenn dieser Drittanbieter Sie selbst ist.

Hier ist ein guter Lackmustest. Wenn Sie der EINZIGE am Projekt wären. Sie wussten, dass Sie der einzige im Projekt sind. Was wäre in Ihrem Kodierungsstandard? Sie möchten, dass Ihr Code in Zukunft sauber, selbsterklärend und für sich selbst verständlich ist. Haben Sie eine Codeüberprüfung mit sich selbst, warum Sie nicht zu jeder Zeile einen Kommentar abgegeben haben? Würden Sie jeden einzelnen Kommentar überprüfen, den Sie zu den 100 eingecheckten Dateien erstellt haben? Wenn nicht, warum dann andere zwingen?

Etwas, von dem ich glaube, dass es in diesen Diskussionen fehlt, ist, dass Future You auch ein Entwickler dieses Projekts ist. Wenn Sie nach dem Wert von morgen fragen, sind Sie auch eine Person, die aus dem Kommentar einen Wert ableiten kann. Die Teamgröße spielt meiner Meinung nach keine Rolle. Teamerfahrung spielt keine Rolle, sie ändert sich zu oft.

Keine Menge an Kommentar-Code, der dies überprüft, verhindert, dass ein Schrittmacher abstürzt und einen Patienten tötet. Wenn Sie über einen Kommentar sprechen, der sich auf den Code auswirkt, sprechen Sie jetzt über den Code und nicht über den Kommentar. Wenn es nur eines fehlenden Kommentars bedarf, um jemanden zu töten, riecht etwas anderes daran.


Die Lösung für diese Art der rigorosen Codierung wurde bereits als Methode zum Schreiben von Software selbst bereitgestellt. Und es hat nichts mit Kommentaren zu tun. Das Problem bei Kommentaren ist, dass sie KEINE Auswirkungen auf die Funktionsweise des Produkts haben. Die besten Kommentare der Welt können nicht verhindern, dass Software abstürzt, wenn sie in einen Schrittmacher eingebettet ist. Oder wenn Sie die elektrischen Signale mit einem tragbaren EKG messen.

Wir haben zwei Arten von Kommentaren:

Maschinenlesbare Kommentare

Kommentarstile wie Javadoc, JSDoc, Doxygen usw. sind alle Möglichkeiten, die öffentliche Schnittstelle zu kommentieren, die ein Satz von Code bereitstellt. Diese Schnittstelle darf nur von einem anderen Entwickler (proprietärer Code für ein Zweierteam), einer unbekannten Anzahl von Entwicklern (z. B. JMS) oder für eine gesamte Abteilung verwendet werden. Dieser Code kann durch einen automatisierten Prozess gelesen werden, der dann eine andere Art des Lesens dieser Kommentare, z. B. HTML, PDF usw., erzeugt.

Diese Art von Kommentaren ist leicht zu erstellen. Es wird ein objektiver Prozess, bei dem sichergestellt wird, dass jede öffentlich aufrufbare Methode, Funktion und Klasse die erforderlichen Kommentare enthält. Überschriften, Parameter, Beschreibung et. el. Dies soll sicherstellen, dass es für ein anderes Team einfach ist, den Code zu finden und zu verwenden.

Ich mache etwas, das verrückt aussieht, aber es ist wirklich nicht

Diese Kommentare sollen anderen helfen, herauszufinden, WARUM dieser Code auf eine bestimmte Weise geschrieben wurde. Möglicherweise liegt ein numerischer Fehler in den Prozessoren vor, auf denen der Code ausgeführt wird, und der Code wird immer abgerundet. Entwickler beschäftigen sich jedoch normalerweise mit Code, der gerundet wird. So kommentieren wir , um sicherzustellen , dass ein Entwickler den Code zu berühren versteht , warum der aktuelle Kontext etwas tut es normalerweise scheint unvernünftig, aber in Wirklichkeit geschrieben wurden auf diese Weise absichtlich.

Diese Art von Code verursacht so viele Probleme. Es bleibt in der Regel unkommentiert und wird später von einem neuen Entwickler gefunden und "behoben". Also alles kaputt machen. Selbst dann sind die Kommentare nur dazu da, das WARUM zu erklären, um nicht zu verhindern, dass etwas kaputt geht.

Auf Kommentare kann man sich nicht verlassen

Kommentare sind letztendlich nutzlos und können nicht als vertrauenswürdig eingestuft werden. Kommentare ändern normalerweise nicht die Art und Weise, wie Programme ausgeführt werden. Und wenn doch, dann verursacht Ihr Prozess mehr Probleme, als es sollte. Kommentare sind nachträgliche Gedanken und können niemals etwas anderes sein. Der Code ist alles, was zählt, da dies alles ist, was vom Computer verarbeitet wird.

Das hört sich vielleicht wie ein Idiot an, aber ertragen Sie es mit mir. Welche dieser beiden Zeilen ist wirklich wichtig?

// We don't divide by 0 in order to stop crashes.

return 1 / n;

In diesem Beispiel kommt es nur darauf an, dass wir keine Ahnung haben, was 'n' ist. Es gibt keine Prüfung, ob n 0 ist, und selbst wenn dies der n = 0Fall ist , hindert nichts einen Entwickler daran, NACH der Prüfung 0 zu setzen ist nutzlos und nichts Automatisiertes kann dies jemals fangen. Kein Standard kann das fangen. Der Kommentar ist zwar hübsch (für einige), hat aber keinen Einfluss auf das Ergebnis des Produkts.

Testgetriebene Entwicklung

Was hat ein Ergebnis auf dem Produkt? Branchen, in denen der geschriebene Code buchstäblich jemanden retten oder töten kann, müssen rigoros überprüft werden. Dies geschieht durch Code-Reviews, Code-Reviews, Testen, Testen, Code-Reviews, Komponententests, Integrationstests, Tests, Staging, monatelange Tests, Code-Reviews und Einzelpersonen-Tests, Staging, Code-Reviews, Testen und schließlich möglicherweise in Produktion gehen. Kommentare haben damit nichts zu tun.

Ich würde eher Code verwenden, der KEINE Kommentare enthielt, eine Spezifikation hatte, Unit-Tests, die die Spezifikation überprüften, Studien über die Ergebnisse der Ausführung des Codes auf dem Produktionsgerät, dann gut dokumentierten Code, der noch nie getestet worden war und nichts zum Vergleichen hatte Code gegen.

Dokumentation ist hilfreich, wenn Sie herausfinden möchten, WARUM jemand etwas auf eine bestimmte Weise getan hat. Im Laufe der Jahre habe ich jedoch festgestellt, dass Dokumentation normalerweise verwendet wird, um zu erklären, warum etwas „Kluges“ getan wurde, wenn es wirklich nicht nötig war so geschrieben sein.

Fazit

Wenn Sie in einem Unternehmen arbeiten, in dem jede Zeile kommentiert werden muss, GARANTIEREN SIE, dass mindestens zwei der Software-Ingenieure im Projekt bereits ein Autodokument-Programm in Perl, Lisp oder Python geschrieben haben, das die allgemeine Vorstellung davon bestimmt, was die Zeile tut und fügt dann einen Kommentar über dieser Zeile hinzu. Da dies möglich ist, bedeutet dies, dass die Kommentare unbrauchbar sind. Suchen Sie nach den Ingenieuren, die diese Skripte geschrieben haben, um den Code automatisch zu dokumentieren, und verwenden Sie sie als Beweis dafür, warum der "Kommentar zu jeder Zeile" Zeit verschwendet, keinen Wert liefert und möglicherweise schädlich ist.

Nebenbei half ich einem engen Freund bei einem Programmierauftrag. Sein Lehrer hatte eine Anforderung gestellt, dass jede Zeile dokumentiert werden musste. So kann ich sehen, woher dieser Denkprozess kommen würde. Fragen Sie sich einfach, was versuchen Sie zu tun, und ist das die richtige Sache? Dann frag dich; Gibt es eine Möglichkeit, das System mit diesem Prozess zu "spielen"? Wenn ja, schafft es dann wirklich einen Mehrwert? Man kann nicht automatisch Komponententests schreiben, bei denen überprüft wird, ob der Code einer bestimmten Spezifikation entspricht, und wenn dies möglich wäre, wäre dies keine schlechte Sache.

Wenn ein Gerät unter bestimmten Bedingungen funktionieren muss, weil es sich im Inneren eines Menschen befindet, ist die einzige Möglichkeit, sicherzustellen, dass es diese nicht tötet, das jahrelange Testen, Überprüfen durch Kollegen, Testen und dann NIEMALS den Code erneut ändern. Dies ist der Grund, warum die NASA solche alte Hard- und Software verwendet. Wenn es um Leben oder Tod geht, nehmen Sie nicht nur eine kleine Änderung vor und checken sie ein.

Kommentare haben nichts damit zu tun, Leben zu retten. Kommentare sind für Menschen, Menschen machen Fehler, auch wenn sie Kommentare schreiben. Vertraue den Menschen nicht. Ergo, traue den Kommentaren nicht. Kommentare sind nicht Ihre Lösung.

Andrew T. Finnell
quelle
3
Das Problem bei Kommentaren ist, dass sie KEINE Auswirkungen auf die Funktionsweise des Produkts haben. gut , wenn der menschliche Teil des Lesens und Schreibens Code zählt Ich denke , dass hat Einfluss darauf, wie es letztlich funktioniert, aber nicht , wie der Code ausgeführt wird, wenn schließlich geschrieben, ja. Ich würde sagen, das Problem mit Code ist einfach, dass er veraltet ist und dann schlimmer ist als kein Code!
Michael Durrant
1
Hier hatten wir einen Zeitnehmer, der tägliche Berichte über unsere Aktivitäten haben wollte, um unsere Arbeit zu optimieren. Auf jeden Fall waren wir ein bisschen verärgert über die Tatsache, dass wir jeden Tag 15 Minuten damit verbringen mussten, sein Formular auszufüllen. Deshalb haben wir dies automatisiert, indem wir Müll aus unseren Protokollen eingefüllt haben.
Joojaa
1
Es gibt ein zusätzliches Problem mit dem Kommentar "Wir teilen nicht durch 0, um Abstürze zu stoppen." Es ist grammatikalisch nicht klar, ob die "in order to" -Klausel für die Aktion der Teilung oder deren Negation gilt. Wenn Sie "Wir vermeiden das Teilen durch 0, um ..." verwenden, vermeiden Sie diese Mehrdeutigkeit. :)
Wildcard
1
"Nicht durch Null teilen, um Abstürze zu stoppen" sagt mir tatsächlich viel über die Denkweise der Person, die es geschrieben hat. Sie codieren nicht, um Abstürze zu vermeiden! Sie codieren so, dass der Code korrekt ist und nicht abstürzt, ist nur ein kleiner Teil der Richtigkeit. Wenn die Berechnung der zu injizierenden Medikamentenmenge durch Null dividiert wird, geben Sie keinen Dummy-Wert wie 99999 ...
immibis
1
@AndrewTFinnell Ich meine, wenn Sie manchmal einen Fehler bei der Division durch Null erhalten, macht das Hinzufügen von "if (divisor == 0) return <something>; // Division durch Null vermeiden" Ihren Code nicht mehr korrekt. Stattdessen müssen Sie herausfinden, warum der Divisor Null ist, und das korrigieren. Einige Algorithmen sind so konzipiert, dass der Nullteiler unvermeidbar ist, aber sie sind die Ausnahme (und in diesem Fall können Sie den Wert "Ergebnis kann nicht berechnet werden" zurückgeben).
immibis
12

Es gibt zwei verschiedene Dinge, auf die Sie anspielen, wenn Sie über Kommentare sprechen. Sie sind nicht gleich, und die Unterscheidung ist wichtig.

Die Dokumentation informiert Sie über die nach außen gerichteten Teile eines Codeteils - seiner Schnittstelle.

Mit den üblichen Werkzeugen können Sie sie "eigenständig" lesen, dh, Sie sehen nicht gleichzeitig den zugrunde liegenden Code.

Die gesamte Schnittstelle sollte dokumentiert sein (z. B. jede Methode, ausgenommen private Methoden) und Eingaben, Ausgaben und sonstige Erwartungen, Einschränkungen usw. beschreiben, insbesondere Dinge, die nicht durch Einschränkungen, Tests usw. ausgedrückt werden können ( Wie genau und wohin es geht, hängt vom jeweiligen Projekt ab.

Durch eine gute Dokumentation kann der potenzielle Verbraucher entscheiden, ob, wann und wie der Code verwendet werden soll.

Kommentare im Quellcode haben einen anderen Zweck. Sie sind für Leute da, die sich den Quellcode ansehen. Sie beschreiben in erster Linie die Implementierung.

Kommentare werden immer im zugrunde liegenden Code eingelesen.

Kommentare sollten überraschende Entscheidungen oder komplexe Algorithmen oder nicht getroffene Optionen (und Argumente) erklären. Sie sind da, damit zukünftige Entwickler die Denkprozesse ihrer Vorgänger verstehen und Informationen zur Hand haben, die sie sonst möglicherweise übersehen oder viel Zeit damit verbringen könnten, z

# 'map' outperforms 'for' here by a factor of 10  

// This line works around an obscure bug in IE10, see issue #12053  

-- We are going to recursively find the parents up to and including the root node.
-- We will then calculate the number of steps from leaf node to root node.
-- We first use a WITH clause to get the ID of the root node.

Sie können nichts aus dem Fehlen eines Kommentars ableiten, und der Kommentar kann natürlich genauso falsch sein wie der umgebende Code oder mehr. Die Beurteilung muss sowohl seitens des Autors als auch seitens des Lesers erfolgen.

Das Kommentieren jeder Zeile ist eindeutig mehr Arbeit von fragwürdigem Mehrwert, was mit Opportunitätskosten verbunden ist. Wenn Sie eine Regel haben , die jede Zeile sagt muss kommentiert werden, erhalten Sie das, aber auf Kosten der wichtigen Teile sind kommentiert gut .

Aber es ist schlimmer als das: Der Zweck eines Kommentars wird beseitigt, wenn jede Zeile kommentiert wird. Kommentare werden zu Geräuschen, die das Lesen von Code erschweren: eher verdecken als klären. Darüber hinaus erschwert wahlloses Kommentieren das Erkennen der wirklich wichtigen Kommentare.

Weder Kommentare noch Dokumentationen bieten irgendeine Art von Maß oder Garantie für die Qualität des von ihnen beschriebenen Codes. Sie sind kein Ersatz für echte Qualitätssicherung. Sie zielen vorausschauend, dh in der Hoffnung, dass sie denjenigen helfen, die damit interagieren, Fehler zu vermeiden.

Zusammenfassend kann und sollte Ihr Kodierungsstandard Dokumentation erfordern (automatische Überprüfungen helfen dabei, undokumentierte Funktionen / Methoden zu erkennen, aber der Mensch muss immer noch prüfen, ob die Dokumentation gut ist). Kommentare sind ein Urteilsspruch und Ihr Styleguide sollte dies anerkennen. Diejenigen, die niemals kommentieren, und diejenigen, die ohne nachzudenken kommentieren, sollten damit rechnen, herausgefordert zu werden.

user52889
quelle
Die öffentliche API zu dokumentieren ist ein guter Punkt, aber ich erkläre wirklich gerne überraschende Entscheidungen. Es ist sehr schön, wenn Verstöße gegen den Grundsatz des geringsten Erstaunens zumindest gerechtfertigt sind. +1
candied_orange
1
+1 für irrelevante Kommentare als Rauschen. Halten Sie das Rauschsignal hoch.
sq33G
+1 speziell für den Zweck eines Kommentars wird beseitigt, wenn jede Zeile kommentiert ist. Schade, dass dies möglicherweise (und häufig) als Entschuldigung dafür verwendet wird, überhaupt nicht zu kommentieren, aber es ist aus den von Ihnen genannten Gründen trotzdem sehr richtig, da die meisten Leute automatisch und verständlicherweise alle Kommentare ignorieren, wenn jede Zeile kommentiert wird .
SantiBailors
10

Sie können einen Kommentierungsstandard nicht kodifizieren, da Sie nicht wissen, wie der wichtige Kommentar im Voraus aussehen wird.

Sie möchten jedoch weiterhin sicherstellen, dass der Code korrekt kommentiert ist, da dies lebenswichtiger Code ist. Die Lösung besteht darin, einen Standard für die Codeüberprüfung zu haben - verlangen Sie, dass die Codeüberprüfung Kommentare zur Verständlichkeit enthält.

Dies garantiert nicht, dass es nicht zu einer bedeutungslosen Checkliste wird, verhindert jedoch zumindest, dass der Code schlechter lesbar wird. Und hat die Möglichkeit, es besser zu machen.

Dies erfordert eine Kultur, in der eine Codeüberprüfung selbst keine bedeutungslose Geste ist, in der es eine gute Sache ist, den Code als schwer lesbar zurückzusenden, und keine Beleidigung oder Belästigung. Genauso wichtig, wenn man sagt, es sei unklar, wird das nicht als Fehler des Lesers angesehen.

Nicht lesbarer Code ist bis zu einem gewissen Grad unvermeidlich. Weil der Autor in den Kontext eingetaucht ist und etwas als offensichtlich ansieht, wenn es nur offensichtlich ist, wenn Sie x, y oder z kennen.

Sie können also keine Regel haben, die besagt, dass Sie ein gutes Feedback geben sollen, aber Sie können die Bewertungen vor Ort überprüfen. Sogar ein Manager ohne Programmierkenntnisse könnte dies tun - denn die eigentliche Frage war nicht, dass der Code so geschrieben wurde, dass er lesbar war, sondern dass der Code tatsächlich lesbar war, was nur von jemandem entschieden werden kann, der ihn liest.

jmoreno
quelle
7
Zu Sie können einen kommentierenden Standard nicht kodifizieren - Sicher können Sie. Sie machen Kommentare der Codeüberprüfung unterworfen, und das Codeüberprüfungselement, das besagt, dass die Kommentare den Code nicht erklären, muss angesprochen werden. Dies ist eine Ausgabe, eine Ausgabe, die die meisten Programmierumgebungen nicht bezahlen möchten. Bei kritischer Software zahlt sich das aus.
David Hammen
"... wenn es nur offensichtlich ist, wenn Sie x, y oder z kennen" Sie können die Menge an Wissen {x, y, z} angeben, die im Voraus bekannt sein muss, um etwas als offensichtlich und dann (Art) zu erkennen mechanisch) können Sie überprüfen, ob dies für den aktuellen Code zutrifft. Wenn nicht, fügen Sie Kommentare hinzu, bis dies der Fall ist.
Trilarion
1
@DavidHammen: Das ist kein Standard für den Kommentar, es ist ein Standard für die Überprüfung. Welches ist, was ich fuhr fort, als die Lösung vorzuschlagen. Sie können nicht sagen, dass es eine bestimmte Größe haben muss oder eine bestimmte Syntax verwenden muss oder dass Sie überhaupt einen Kommentar benötigen (oder Sie erhalten Kommentare vom Typ "add one to i"). Sie KÖNNEN sagen, dass der Prüfer den Code und die Kommentare kommentieren muss. Wie Sie sagen, können Sie verlangen, dass Probleme, die durch die Codeüberprüfung aufgeworfen werden, behoben werden. Die Verantwortung dafür muss jedoch beim Rezensenten liegen, um gute Arbeit zu leisten. Nur der Prüfer kann beurteilen, ob der Code und der Kommentar ausreichen.
Jmoreno
@DavidHammen Die Personen, die für die Überprüfung ausgewählt wurden, geben das Urteil ab. Und wenn sie gehen? Wenn neue Leute nicht so denken oder Englisch sprechen? Wenn die 'Reviewer' gehen? Ihr Vorschlag stellt einige Entwickler auf einen Elfenbeinturm, was zu Meinungsverschiedenheiten, Misstrauen und Kommunikationsstörungen führt. Kommentare sollen denjenigen, die sie verwenden können, Einblicke oder Erläuterungen geben. Vielleicht braucht Joe es, aber Mary nicht. Was passiert, wenn Mary die Rezensentin ist? Oder Joe? Oder Markus?
Andrew T Finnell
@jmoreno - Wenn Programmierer keine Regeln / Richtlinien zu Kommentaren in die Kodierungsstandards einfügen, müssen sie mehrere Quellen betrachten - und sie wissen nicht, wo sie suchen müssen, bis die Überprüfung zurückkommt und sagt, dass die Kommentare nicht den Standards entsprechen. Es ist ein Fehler zu glauben, dass alles in einem Codierungsstandard automatisierbar sein muss. Beispielsweise sind Regeln für sinnvolle Namen nicht automatisierbar. Zumindest jetzt noch nicht. Zum Beispiel x, yund z, oder i, jund kkann durchaus sinnvolle Namen sein , wenn man einen wissenschaftlichen Algorithmus basiert auf einem Journalpapier implementieren, die genau in ihren Formeln die Namen verwendet.
David Hammen
9

Jede Codezeile kommentieren? Nein .

Der Zweck der anderen Regeln, über die Sie sprechen, ist genau das zu vermeiden.

Kommentare zu einem lesbaren Code sind bestenfalls überflüssig und lenken den Leser im schlimmsten Fall davon ab, nach dem nicht existierenden Zweck des Kommentars zu suchen.

Wenn Sie den gesamten Code kommentieren, der selbsterklärend ist, verdoppeln Sie die Anzahl der Lesevorgänge, ohne zusätzliche Informationen anzugeben. Ich bin mir nicht sicher, ob sich eine solche Redundanz auszahlen würde. Man kann sich vorstellen, dass ein Rezensent sagt, dass 42 " display_error" sagt, während der Kommentar "Warnung anzeigt". Stellen Sie sich aber eine Änderung im Code vor. Sie müssen jetzt zwei Stellen korrigieren. Es wird deutlich, dass dieser Stil Copy-Paste-Negative enthält.

Ich würde sagen, dass der Code, abgesehen von der Dokumentation, im Idealfall keine Kommentare benötigen sollte.

Es gibt Stile, bei denen das Gegenteil der Fall ist. Wenn Sie Zweifel an der Linie haben, ist es entweder:

  1. Der Code ist zu kompliziert und sollte in eine Funktion mit einem Namen umgewandelt werden, der eine semantische Bedeutung für den Teil des Codes hat. Sei es ein komplexer ifoder ein Teil eines Algorithmus. (Oder ein cleverer LINQ-Einzeiler)

  2. Wenn es nicht vereinfacht werden kann, kennen Sie nicht genug Redewendungen.

(Ich persönlich bin kein Fan der strengen No-Comments-Regel, aber ich finde, dass dies eine gute Grundeinstellung ist.)

Ist es angesichts all dessen überhaupt möglich, gute Codierungsstandards zu schreiben, die diese Idee aufgreifen?

Wie für den Prozess. Unser Standard hat dem Rezensenten ziemlich viel Anerkennung geschenkt. Vorausgesetzt, sie sind nicht böswillig, funktioniert dies gut.

Wenn er fragt "Was ist variabel o?", Benennen Sie es um. Wenn er fragt, was dieser Block macht, entweder umgestalten oder kommentieren. Wenn es eine Debatte gab, ob etwas klar ist oder nicht, wenn der Prüfer es nicht verstanden hat, dann ist es per Definition nicht. In sehr seltenen Fällen gab es so etwas wie eine Zweitmeinung von wenigen Freunden.

Im Durchschnitt sollten Sie einen Code erhalten, der für den durchschnittlichen Programmierer im Team verständlich ist. IMO hält es die redundanten Informationen fern und stellt sicher, dass der Code für mindestens ein anderes Mitglied des Teams verständlich ist, was wir für ein gutes Optimum befunden haben.

Auch gab es keine absoluten . Obwohl wir eine kleine Gruppe waren. Es ist leicht, einen Konsens in 5er-Gruppen zu finden.

luk32
quelle
2
Das Verwenden von Codeüberprüfungen, um festzulegen, welche Variablen, Klassen und Methoden benannt werden sollen, ist der beste Weg, um Menschen dazu zu bringen, ein Unternehmen, Unternehmen oder eine Methode zu hassen. Codeüberprüfungen sollten nicht dazu verwendet werden, Dinge durchzusetzen, die nicht wirklich wichtig sind. Ein Kodierungsstandard muss über einen automatisierten Prozess überprüfbar sein. Variable Namenslänge, zirkuläre Komplexität, Demeter-Gesetz sind alles Dinge, die überprüft werden können. Wenn jemand mir sagte, ich solle eine Variable von 'i' in so etwas wie indexForThePreviousCollection umbenennen, würde ich einen anderen Arbeitsplatz finden. Variablen> 3 Zeichen werden alle vor dem Einchecken automatisch überprüft.
Andrew T Finnell
3
@AndrewTFinnell Ich kann unmöglich schreiben, Code in jedem Programmierparadigma zu folgen, das Sie benennen möchten.
candied_orange
2
@ AndrewTFinnell Nun, ich werde höflich anderer Meinung sein. " Verwenden von Code-Überprüfungen zum Diktieren ", ich weiß nicht, woher Sie das gezogen haben. Ich würde nicht mit Variablen auf den Code arbeiten i, j, kalle über den Ort , nachdem der ursprüngliche Autor beendet. Ich verstehe Ihren Standpunkt zum "menschlichen" Genom nicht. Ich bezweifle, dass es eine Sprache gibt, in der einzelne Aussagen oder zwei zu schwer zu verstehen sind. Wie gesagt, ich habe komplexe ifs und LINQEinzeiler gesehen. Sie können unter einem semantisch aussagekräftigen Namen kommentiert oder überarbeitet werden. Ich denke, das ist Ihr "guter Kommentar".
Luk32
3
@ Luk32 Ich respektiere das Recht zu widersprechen. Iterationsvariablen sind meiner Meinung nach ziemlich kontextuell offensichtlich. Obwohl ich das Gefühl Ihrer Aussage verstehe, glaube ich, dass es zu viele Praktiken gibt, die dieses Gefühl auf die Spitze treiben. Brauchen wir wirklich Code, der lautet: for (int indexForCurrentDatabaseRow = 0; indexForCurrentDatabaseRow < currentUserRecordSetResults.length; indexForCurrentDatabaseRow = indexForCurrentDatabaseRow + 1)versus for (int i = 0; i < results.length; i++)? Vielleicht ist es eine Frage der Präferenz und / oder des Zeitaufwands beim Betrachten von Code. Übermäßig wortreiche Namen riechen für mich.
Andrew T Finnell
2
Ich denke nicht, dass die Namen in Code-Reviews festgelegt werden sollten. Die Codeüberprüfung sollte normalerweise beginnen, nachdem der Autor der Meinung ist, dass sie gut genug ist. Dies bedeutet auch, dass sie ordnungsgemäß kommentiert und leicht verständlich ist und die Variablen anständige Namen haben. Die Sache ist - wenn die Rezensenten den Code für zu kompliziert halten oder mit der Bedeutung einer Variablen zu kämpfen haben, ist der Code schwer zu verstehen. Dies ist nicht umstritten - offensichtlich hat mindestens ein Entwickler - der Rezensent - es nicht verstanden. Ob es überarbeitet (und wie) oder richtig kommentiert werden muss, ist eine andere Frage.
Idan Arye
9

Die Frage:

Ist es angesichts all dessen überhaupt möglich, gute Codierungsstandards zu schreiben, die diese Idee aufgreifen? Personen, die für eine Begutachtung relevant sind, sich jedoch nicht in eine sinnlose Checklistenaktivität verwandeln, die Notizen erstellt, die nicht hilfreicher sind als: "Sie haben vergessen, in Zeile 42 einen Kommentar abzugeben".

Kommentare sollten nicht darauf abzielen, den Leser über die Sprache zu unterrichten. Es sollte davon ausgegangen werden, dass ein Leser die Sprache besser kennt als der Verfasser, aber mit viel weniger Kontext als der Verfasser.

Ein Leser dieses Codes aus Ihrem Beispiel sollte wissen, dass exit()die Anwendung beendet wird, wodurch der Kommentar überflüssig wird:

/* Exit the application */
exit();

Redundante Kommentare stellen eine Verletzung von DRY dar, und Änderungen am Code werden nicht notwendigerweise auf die Kommentare übertragen, sodass Kommentare verbleiben, die nicht die tatsächliche Funktionsweise des Codes widerspiegeln.

Kommentare, die erklären, warum Sie etwas tun, können jedoch wertvoll sein - insbesondere, wenn Sie die Bedeutung im Code selbst nicht leicht kommunizieren können.

Pythons PEP 8 (der Styleguide für Python in der CPython-Standardbibliothek) bietet die folgende Richtlinie für Inline-Kommentare:

Verwenden Sie Inline-Kommentare sparsam.

Ein Inline-Kommentar ist ein Kommentar in derselben Zeile wie eine Anweisung. Inline-Kommentare sollten durch mindestens zwei Leerzeichen von der Anweisung getrennt werden. Sie sollten mit einem # und einem Leerzeichen beginnen.

Inline-Kommentare sind unnötig und lenken tatsächlich ab, wenn sie das Offensichtliche angeben. Mach das nicht:

x = x + 1                 # Increment x

Aber manchmal ist das nützlich:

x = x + 1                 # Compensate for border

Angesichts eines solchen Beispiels gehe ich persönlich lieber noch einen Schritt weiter und würde versuchen, diesen Kommentar ebenfalls zu beseitigen. Zum Beispiel könnte ich ankommen:

border_compensation = 1
compensated_x = x + border_compensation

Die Selbstdokumentation Ihres Codes ist keine neue Idee .

Zurück zur eigentlichen Frage:

Ist es angesichts all dessen überhaupt möglich, gute Codierungsstandards zu schreiben, die diese Idee aufgreifen?

Ich glaube, dass die PEP 8-Anleitung und das PEP 8-Beispiel einen guten Kodierungsstandard aufzeigen, der diese Idee aufgreift. Also ja, ich glaube es ist möglich.

Aaron Hall
quelle
1
"Es sollte angenommen werden, dass ein Leser die Sprache besser kennt als der Schriftsteller." Es fällt mir schwer zu glauben, dass dies die richtige Einstellung ist. Ich kann davon ausgehen, dass sie so viel wissen , aber jedes Team ist anders und jede Person in einem Team ist anders. Eine pauschale Aussage zu diesem bestimmten Punkt scheint also nicht klug zu sein.
Bryan Oakley
4
Ohne diese Anleitung müssen Junior-Programmierer Kommentare abgeben, in denen sie nur sich selbst den trivialen Code erklären, und Midlevel-Programmierer, die umständliche Lösungen verwenden, um den Code für Junior-Programmierer einfacher zugänglich zu machen. Diese Anleitung beseitigt Redundanz und stellt sicher, dass auch ein erfahrener Programmierer seinen Code weiter verbessert. Wenn ich Code selbst überarbeite, habe ich vielleicht den Kontext vergessen, aber im Allgemeinen weiß ich, was die Sprache noch besser macht, als beim ersten Schreiben.
Aaron Hall
4

Ich denke, wenn Sie diese Art von Kommentaren sehen und ich selbst gelegentlich so schreibe, liegt es daran, dass der Autor die Spezifikation in die Kommentare schreibt und dann jeden Kommentar durchläuft und umsetzt.

Wenn wir aufgefordert werden, einen Codierungsstandard zu schreiben, der Code erzeugt, der in Bezug auf die erforderliche Funktionalität verständlich ist und nicht in Bezug auf die tatsächliche Funktionalität (damit Fehler entdeckt werden können), dann sprechen wir wirklich darüber, wie die Spezifikationen definiert, dokumentiert und verknüpft werden das Endprodukt?

bearbeiten ----

Nur um klarzustellen. Ich gehe nicht auf Kommentare gegen Tdd gegen Unit-Tests ein, die am besten sind. Oder einen Kommentar pro Zeile vorzuschlagen ist gut / schlecht

Ich schlage nur einen Grund vor, warum Sie den Kommentierungsstil sehen, über den im Beispiel gesprochen wird.

Und aus dieser Frage heraus, ob ein Kodierungsstandard zum Kommentieren tatsächlich besser als eine Art Spezifikationsdokument geschrieben werden könnte.

dh Kommentare dienen zur Erläuterung des Zwecks des Codes, was auch eine Spezifikation ist

Ewan
quelle
6
In 20 Jahren habe ich noch nie einen Kommentar-Prototypen gesehen, der seinen Code auf diese Weise erstellt und dann die Lücken mit tatsächlichem Code gefüllt hat. Es gibt bereits einen objektiven Weg, um zu erreichen, was Sie sagen oder was Sie sagen. Es heißt Test Driven Development. Die Unit Tests definieren die Spezifikation und ob der Code dieser Spezifikation entspricht. Alles ohne Kommentare.
Andrew T Finnell
9
Obwohl ich nicht der Meinung bin, dass der Code in der Frage ein gutes Beispiel dafür ist, wird die Praxis, zuerst eine Prozedur in Kommentare zu schreiben und dann zurückzugehen und den Code auszufüllen, in "Code Complete" speziell als Eins bezeichnet Mögliche Vorgehensweise zum Erstellen von lesbarem Code: @AndrewTFinnell. Es ist definitiv nicht ungewöhnlich, auch wenn es außerhalb Ihrer Erfahrung liegt.
Josh Caswell
6
Ich glaube, auch älter als tdd
Ewan
2
Sprechen Sie über den Pseudocode-Programmierprozess? Der Zweck war es, Kommentare zu reduzieren. Ich kann mich nicht erinnern, dass das Buch mit den Kommentaren im Code belassen werden sollte. Und das Kommentieren, um ein konzeptionelles Verfahren zu erstellen, soll ein hohes Niveau sein, nicht ein niedriges. Wenn man jede Zeile, die sie schreiben wollten, kommentieren würde, hätte man die Zeilen einfach schreiben können. Die Idee ist, die Prinzipien des Codes zu prototypisieren, nicht jede Zeile. Das Buch schlägt nicht vor, jede Zeile zu kommentieren. Das ist der Schwerpunkt dieser Frage. Und ich könnte mich irren, aber ich glaube, das ist in der zweiten Auflage.
Andrew T Finnell
2
@JoshCaswell & Ewan, ja, es war vor vielen Jahren eine Technik und war tatsächlich älter als TDD. Sie sollten die Kommentare jedoch nachträglich löschen! Und TDD hat es als sinnvolle Methode zur Erstellung von Code, der einer Spezifikation entspricht, komplett abgelöst.
David Arno
4

Ist es angesichts all dessen überhaupt möglich, gute Codierungsstandards zu schreiben, die diese Idee aufgreifen? Personen, die für eine Begutachtung relevant sind, sich jedoch nicht in eine sinnlose Checklistenaktivität verwandeln, die Notizen erstellt, die nicht hilfreicher sind als: "Sie haben vergessen, in Zeile 42 einen Kommentar abzugeben".

Dies geht offensichtlich über die Dokumentation hinaus - dies betrifft die Struktur des Codes, die Auswahl der Algorithmen usw. Es kann sogar die Analyse und das Design der Anforderungen betreffen.

Meine Regel Nummer 1 lautet: "Dokumentieren Sie nicht das Offensichtliche." Die Regel Nr. 2 lautet "Offensichtlichen Code schreiben".

Für sicherheitskritischen Code (an dem ich Gott sei Dank nie arbeiten musste) ist dies ein notwendiger, aber bei weitem nicht ausreichender erster Schritt. Es kann sogar sein, dass es darauf ankommt, festzulegen, welche Sprachfunktionen vermieden werden müssen (ich habe mehr als ein Standardmandat "Du sollst scanf( "%s", input ); aus keinem Grund verwenden " gesehen).

John Bode
quelle
Offensichtlich liegt es im Auge des Betrachters. Und ändert sich je nach Frist.
Tony Ennis
3

Die Best Practice für selbstdokumentierenden Code ist kein allgemeiner Konsens. Obwohl es allgemein akzeptabel ist, dass leicht verständlicher Code besser ist als kryptischer Code, sind sich nicht alle einig, ob komplizierter Code immer überarbeitet werden muss oder ob es in Ordnung ist, Kommentare abzugeben es.

Aber diese Debatte geht es um Stücke von Code, sind schwer zu verstehen - und Sie sprechen zu kommentieren jede einzelne Codezeile. Schwierig zu verstehende Codezeilen sollten sehr selten vorkommen - wenn die meisten Ihrer Zeilen so kompliziert sind, überstrapazieren Sie kluge Einzeiler und sollten aufhören! Sicher, die Rolle einer Zeile ist manchmal etwas schwer zu verstehen, aber das ist die Rolle im Zusammenhang mit einem größeren Teil des Codes - was die Zeile selbst tut, ist fast immer einfach.

Sie sollten also keine Zeilen kommentieren - Sie sollten Teile des Codes kommentieren. Bestimmte Kommentare können in der Nähe der Zeilen platziert werden, auf die sie sich beziehen, aber diese Kommentare beziehen sich immer noch auf den größeren Code. Sie beschreiben nicht, was / warum die Zeile tut - sie beschreiben, was sie in diesem Code tut und / oder warum sie in diesem Code benötigt wird.

Es sollten also keine Zeilen kommentiert werden, sondern größere Codeteile. Sollte jeder Code kommentiert werden? Nein. Harold Abelson sagte, dass " Programme geschrieben werden müssen, damit Menschen sie lesen können, und nur im Übrigen, damit Maschinen ausgeführt werden können ". Kommentare sind jedoch nur für Benutzer lesbar - die Maschine führt sie nicht aus. Wenn Ihre Codierungsstandards das Schreiben redundanter Kommentare zu jeder Zeile / jedem Codeteil erzwingen, belasten Sie nicht nur den Entwickler, der sie schreiben muss, sondern auch die Entwickler, die sie lesen müssen!

Dies ist ein Problem, denn wenn die meisten von Ihnen gelesenen Kommentare überflüssig sind, hören Sie auf, auf sie zu achten (weil Sie wissen, dass es sich nur um überflüssigen Müll handelt), und dann verpassen Sie die wichtigen Kommentare. Also sage ich - schreibe nur den wichtigen Kommentar, damit jemand, der einen Kommentar im Code sieht, weiß, dass es sich lohnt, ihn zu lesen, um den Code zu verstehen.

Idan Arye
quelle
1
Verpassen Sie die wichtigen Kommentare: +1. Der Satz, der mit "Sie beschreiben nicht" beginnt, könnte eine gewisse Umstrukturierung gebrauchen, um die Verfolgung zu erleichtern.
candied_orange
3

IMHO sollte es beides tun. Das Kommentieren jeder Zeile ist albern, weil Sie mit Zeilen wie enden

  i++;    /* Increment i */

mit absolut keiner Ahnung, warum Sie i erhöhen möchten. Erweitern Sie das ein wenig, und Sie haben den typischen Doxygen-Stil von Kommentaren, die eine große Menge an Ausdruck erzeugen, ohne eine Vorstellung davon zu haben, wofür der Code gedacht ist oder wie er funktioniert. (Zumindest soweit ich je gesehen habe: Ich gebe zu, dass es mit einem solchen System möglich sein könnte, nützliche Dokumentationen zu schreiben, aber ich halte nicht den Atem an.)

OTOH, wenn Sie einen guten Kommentarblock am Anfang der Funktion schreiben (oder welche Gruppierung auch immer logisch ist), der sowohl beschreibt, was erreicht werden soll, als auch, wie Sie, wenn es nicht offensichtlich ist, etwas Nützliches haben. Wenn Sie ich sind, können Sie sogar LaTeX-Code für relevante Gleichungen oder Verweise auf Artikel einfügen, z. B. "Dies implementiert ein WENO-Schema zum Lösen von Hamilton-Jacobi-Gleichungen, wie in ...".

jamesqf
quelle
2
+1 für den Sauerstoffkommentar: Dies ist genau mein Einwand gegen die Aufnahme von Sauerstoff "Dokumentation" in meinen Code; In 95% der Fälle wiederholt es nur das, was bereits aus der Funktionssignatur ersichtlich ist. Auch ich habe noch keine einzige Sauerstoffdokumentation gesehen, die irgendetwas wert ist. Das Schreiben dieser Kommentare kostet dreimal Zeit: Einmal, um die Kommentare zu schreiben, einmal, um sie erneut zu lesen und einmal, um Probleme zu beheben, die durch veralteten Kommentarinhalt verursacht wurden.
cmaster
1
Widersprichst du dir nicht? Ich denke, wir sind uns einig, dass es für eine Funktion entscheidend ist, einen Kommentar zu verfassen, der beschreibt, was sie aus einer Black-Box-Perspektive tut - "diese Eingaben gehen ein, die Funktion macht dies und diese Ausgaben kommen heraus". Es bildet den Vertrag zwischen der Person, die die Funktion geschrieben hat, und den Personen, die die Funktion nutzen. Der Zweck von Doxygen besteht einfach darin, das Format dieser Kommentare auf eine Weise zu standardisieren, die analysiert und durchsuchbar / indexierbar gemacht werden kann. Warum sollten Sie also einen "guten Kommentarblock" wünschen, aber nicht ein Standardformat, das von Menschen und Maschinen gelesen werden kann?
Graham
Die Verwendung eines Kommentar-Standards wie JSDoc, JavaDoc und Doxygen ist dazu gedacht, durchsuchbare und für Menschen lesbare Dokumentationen bereitzustellen, wie @Graham sagte. Die in dieser Antwort erwähnte Codezeile hat nichts mit Doxygen zu tun. Ich kann mir nicht einmal vorstellen, dass ein Regelsatz vorhanden ist, der diesen Kommentar analysiert und einen Eintrag in der ausgegebenen Dokumentation erzeugt. Wenn Sie sich die Dokumente für JMI, die Java-Standardbibliotheken usw. ansehen, werden sie alle mit einem Tool erstellt, das Doxygen sehr ähnlich ist. Das ist der Zweck davon. Nicht das, was hier gesagt wird
Andrew T Finnell
Ich denke mir das nicht aus - um eine kanadische Anforderung zu erfüllen, ließ eine Firma, bei der ich gearbeitet habe, die Entwickler einen Pre-Prozessor schreiben, der genau wie das OP-Beispiel Kommentare hinzufügte. Ich denke, unsere war "C ADD 1 TO I" oder so. Es war FORTRAN, daher wurden Loops ähnlich empfohlen: "C LOOP FROM 1 TO 10". Der Code wurde mit nutzlosen Kommentaren geladen. Ich habe den ganzen Mist gelöscht, als ich den Code gepflegt habe. Niemand hat jemals etwas zu mir gesagt.
Tony Ennis
2

Es ist Zeit, Flussdiagramme zurückzubringen! (nicht wirklich, aber warte eine Minute)

Neulich habe ich meine alte Flowchart-Vorlage gefunden. Ich habe es nur für Hausaufgaben und Witze benutzt (du musst ein gutes, albernes Flussdiagramm lieben). Aber selbst zu diesem Zeitpunkt generierten die meisten kommerziellen Programmierer, die noch Flussdiagramme verwendeten, diese automatisch aus dem Code (was den ursprünglichen Zweck des Flussdiagramms vollständig untergräbt, das dazu dienen sollte, besseren Code zu schreiben und im Maschinencode sehr nützlich war). Bei höheren Sprachen hat sich das Flussdiagramm jedoch von einer Krücke zu einem Humpel gewandelt. Warum? Die Abstraktion des Flussdiagramms war dieselbe wie der Code. Die gezeigten Kommentare sind insofern ein Humpel, als sie sich auf derselben Abstraktionsstufe wie der Code befinden. Gute Kommentare befinden sich auf einer anderen Abstraktionsebene als der Code. Der einfachste Weg, dies zu tun, besteht darin, Kommentare für das Warum zu verwenden, während der Code was verarbeitet.

hildred
quelle
Es tut mir leid, Ihnen mitteilen zu müssen, dass Flussdiagramme nie verschwunden sind.
Ant P
Gute Kommentare haben eine andere Abstraktionsebene als der Code . Hört hört!
candied_orange
1
Obwohl dies ein anständiger Rat sein mag, scheint er die gestellte Frage nicht zu beantworten, außer vielleicht einen einzigen Satz.
Bryan Oakley
0

Ich beantworte die Frage wie folgt:

Ist es angesichts all dessen überhaupt möglich, gute Codierungsstandards zu schreiben, die diese Idee aufgreifen?

Ja. WYSIWYG. Ein guter Kodierungsstandard lautet wörtlich: " Dem Leser ist klar, was der folgende Code tut und warum ".

Mit anderen Worten, meine Kommentare zum Code-Review über die Lesbarkeit im wahrsten Sinne des Wortes, 1-1, ergeben sich aus meinem mentalen Zustand von

Ich als Leser (besser noch als Minimalstandard, als mentales Modell eines weniger erfahrenen, aber vernünftigen Lesers) würde den Zweck oder die Arbeitsweise des folgenden Codes nicht verstehen

Im Allgemeinen fällt es den Leuten leicht, an Bord zu kommen, "das braucht mehr Lesbarkeit", wenn sie hören, "dass ich als leitender Entwickler, den Sie hoffentlich als nicht dumm ansehen, diesen Code zunächst nicht verstanden habe oder warum er dort ist oder was er ist muss erklärt werden ".

Dies verschiebt den Diskurs von "Sie haben keinen bedeutungslosen Standard befolgt" zu "Ihr Code weist eine spezifische Lesbarkeitslücke auf, die zu praktischen Problemen führt ".

Ein zweiter Standard, der explizit formuliert werden muss, ist der "2-Uhr-Notfalltest".

Kann Ihr Backup, das noch keine Erfahrung mit diesem Code hat, herausfinden, wo das Problem mit dem Code liegt, wenn es während eines Notrufs um 2 Uhr morgens in der Produktion debuggt, wenn Sie in den chilenischen Anden ohne Handy im Urlaub sind?

Dies mag subjektiv klingen, ist aber praktisch leicht zu messen: Rufen Sie ein zufälliges Junior-Teammitglied an, von dem erwartet wird, dass es nachts im Produktionsnotfall das Debugging durchführt, und bitten Sie es, zu erklären, wie der bestimmte unkommentierte Code funktioniert und warum er funktioniert Dort.

DVK
quelle
0

Diese Antwort deckte die meisten Fragen ab, es gibt jedoch eine wichtige Sache.

Ich möchte eine Idee wie folgt erfassen: Betrachten Sie einen Kommentar für jede Zeile, Sequenz, Anweisung, Abschnitt, Struktur, Funktion, Methode, Klasse, Paket, Komponente, ... des Codes.

Es gibt Tools zum Generieren von Dokumentation aus Code, wie zum Beispiel Doxygen. Wenn Sie solche Tools verwenden, ist es sinnvoll, Dateien, Funktionen, Klassen usw. zu kommentieren. Auch wenn der Name der Funktion selbsterklärend ist, mache ich dies aus Gründen der Konsistenz, da die Leute, die die Dokumentation lesen, dankbar sein werden.

BЈовић
quelle
1
Aber die "Dokumentation", die mit solchen Tools erstellt wird, ist meiner Erfahrung nach im Allgemeinen weniger wert als gar keine Dokumentation, da sie dem Benutzer keine nützlichen Informationen liefert (und ihn dazu veranlasst, Zeit zu verschwenden, um zu versuchen, die nicht existent info), aber täuscht die Entwickler in der Annahme, dass sie ihren Code richtig dokumentiert haben.
Jamesqf
@jamesqf Ja, wenn die Hälfte der Funktionen nicht und die andere Hälfte schlecht dokumentiert ist. Doxygen kann jedoch erzeugen recht gute Dokumentation, Entwickler richtig kommentierte ihre Funktionen unter der Annahme, Klassen, etc.
BЈовић
-1

Viele der vorhandenen Antworten sind sehr detailliert, aber ich fand es wichtig zu antworten:

... [Kommentare], die für ein Peer Review relevant sind, sich aber nicht in eine sinnlose Checklistenaktivität verwandeln ...

Für mich können die einzigen Kommentare, die ein Standard sein könnten, durch die Frage beantwortet werden, welche Kommentare bemerkt werden, wenn sie fehlen . Mit anderen Worten: Kommentare, die von IDEs oder Dokumentationssoftware verwendet werden.

Dies hängt jedoch davon ab, welche Tools von den Entwicklern verwendet werden, und nicht alle Kommentare, die von einer solchen Software verwendet werden, sind so nützlich wie die anderen .

Erdrik Ironrose
quelle