Codierungsstandard für Klarheit: Jede Codezeile kommentieren?

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

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.

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

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.

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.

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.

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.

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.

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.

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.

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

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).

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.

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 ...".

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.

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.

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.

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 .