Wie man gute Codekommentare schreibt: "Warum", nicht "Wie"

Hallo Habr! Ich präsentiere Ihnen die Übersetzung des Artikels "Gute Kommentare schreiben: das Warum, nicht das Wie" von Jack Franklin.







Das Auskommentieren von Code in einer Programmierumgebung wird häufig als Zeitverschwendung oder als Signal dafür angesehen, dass der Code verbessert werden kann. Hier ist ein Zitat aus der Datei CONTRIBUTING.md, die ich auf GitHub gefunden habe (und es gibt viele solcher Beispiele):

Kommentare sollten vermieden werden. Wenn Ihr Code ohne Kommentare nicht verstanden werden kann, schreiben Sie ihn neu, um sich selbst zu erklären.

Ich glaube, dass solche Ratschläge in den meisten Fällen erfolglos und falsch sind. Ich glaube, dieser Ansatz hat seine Wurzeln in den Lernerfahrungen der meisten Menschen, die Programmieren studiert haben. Als ich an der Universität Informatik studierte (obwohl dieser Rat in vielen Kursen zu finden ist, nicht unbedingt in Universitätskursen), erinnere ich mich sehr an einen Lehrer im ersten Semester, der sagte:

Jede Codezeile sollte einen Kommentar enthalten, der erklärt, was sie tut. Ihre Arbeit im Kurs wird nach diesem Kriterium beurteilt.

Nehmen wir also an, Sie sind ein frisch gebackener Student, der gerade mit diesem Kurs beginnt. Was werden sie machen? Kommentar zum Code natürlich!

//      bar
const inputValue = process.ENV.bar

//     2
const newValue = inputValue * 2

//     square
const finalValue = square(newValue)

//         
const square = (x) => x * x

Leute, die sagen, dass Kommentare schlecht sind, denken tatsächlich über solche Kommentare nach. Und sie haben absolut Recht! Kommentare wie die oben genannten, die die Frage "Wie?" Beantworten, sind bei der Programmierung völlig nutzlos. Alle diese Kommentare haben dem Code nichts hinzugefügt, was aus dem Code selbst nicht verstanden werden kann.

Beantworten Sie die Frage "Warum?"

Das Problem mit den obigen Kommentaren ist, dass sie erklären, wie . Erklärt die Schritte, die wir im Code unternehmen. Solche Kommentare sind selten hilfreich; Der Code selbst kann Ihnen viel besser sagen, was zu tun ist. Schließlich sind Codezeilen nur Anweisungen, die dem Computer mitteilen, wie eine Aufgabe ausgeführt werden soll.



Normalerweise ist keine Fülle von Kommentaren erforderlich, da Sie einfachen Code ohne Funktionen oder Nuancen schreiben können, die ihm ein unverständliches Aussehen verleihen würden. Manchmal treten jedoch Situationen auf, in denen es unmöglich ist, elementaren und intuitiven Code zu schreiben. Vielleicht ist es ein Fehler, den Sie umgehen müssen. Oder Sie haben das Glück von früheren Entwicklern in Form eines Systems geerbt, das Sie daran hindert, das Problem so zu lösen, wie Sie es möchten. Letztendlich gibt es einfach keine einfache Möglichkeit, Ihren Code zu verbessern.



Einmal habe ich in einer Verarbeitungsfirma gearbeitet. Jeden Tag führten wir eine große SQL-Abfrage durch, in der die zu zahlenden Zahlungen ausgewählt wurden. Die Abfrage war gut optimiert - wir mussten sehr schnell sein - und dabei äußerst komplex: Es gab viele Randfälle zu berücksichtigen. Wir haben uns sehr bemüht, dies so klar wie möglich zu machen. Diese Anfrage könnte jedoch niemals vollständig intuitiv und leicht verständlich sein. Es enthielt einfach zu viel Code mit einer Reihe von Bedingungen und Logik, die nur im Kontext unseres Unternehmens und seiner Funktionsweise verstanden werden konnten.



Ich wollte hier ein Beispiel finden, um es zu zeigen, also ging ich in die Wildnis der React-Codebasis, um etwas zu finden. Sie müssen kein React-Entwickler sein, um es herauszufinden. Hier ist der Code, den ich hervorheben möchte:

//  key     .    , 
//  key      (, <div {...props} key="Hi" />
//  <div key="Hi" {...props} /> ).     key,   ,
//      jsxDEV   , 
// <div {...props} key="Hi" />,       ,
//    key   . 
if (maybeKey !== undefined) {
  key = '' + maybeKey
}

( Und hier ist ein Link dazu auf GitHub ).



Achten Sie auf den Code selbst:

if (maybeKey !== undefined) {
  key = '' + maybeKey
}

Es ist nicht so schwer herauszufinden, was es tut. Wenn vielleichtKey nicht angegeben ist, weisen wir key den stringifizierten MaybeKey-Wert zu. Hinweis: Dies ist ein kleiner JavaScript-Trick, '' + maybeKeyum den Inhalt von MaybeKey in eine Zeichenfolge zu konvertieren.



Aber hier ist die ganze Frage, warum . Der Kommentar zu diesem Code ist großartig. Er weist auf das Problem hin, gibt zwei Beispiele und erklärt auch, wie dieses Problem langfristig gelöst werden kann und was wir kurzfristig tun.



Wenn Sie sich einen Kommentar ansehen möchten, den ich in dem von mir geschriebenen Code hinterlassen habe, finden Sie hier einen (TypeScript / Closure Compiler) . Dies ist ein gutes Beispiel für die Art von Kommentaren, die ich sehr wertvoll finde.



Am Ende kann jeder Code verstanden werden. Code ist schließlich nichts anderes als Anweisungen, die dem Computer mitteilen, wie er vorgehen soll. Der Code kann verwirrend sein, aber er kann nicht lügen. Wenn die Zeit ausreicht, kann jeder Entwickler den Code Schritt für Schritt durchgehen und verstehen, was er tut. Manchmal ist es viel schwieriger zu verstehen, warum er es tut. Lassen Sie Ihren Mitarbeitern (oder in sechs Monaten in der Zukunft) einen Kontext darüber, warum und wofür Ihr Code das tut, was er tut. Es wird viel besser sein.