Ich versuche, meinen Code von zukünftigen Lesern leicht verständlich zu machen.
Ich hatte schon immer Probleme mit der Formulierung meiner if-Statement-Kommentare, um sie am verständlichsten zu machen.
Vielleicht scheint es trivial, aber es ist etwas, das mich immer gestört hat
Hier ist ein Beispiel:
%Vor%Hier sind einige Möglichkeiten, wie ich es kommentieren kann
%Vor%Nicht das beste Beispiel, aber die Art, wie ich es dort sehe, gibt es unendlich viele Möglichkeiten, es zu formulieren.
Ich habe noch nie wirklich an einem Team gearbeitet, deshalb habe ich nicht viel Erfahrung mit anderen Leuten, die meinen Code lesen.
Was sind Ihre Erfahrungen auf dem besten Weg, dies zu formulieren, um es für zukünftige Programmierer lesbar zu machen.
Für die von Ihnen angegebenen Fälle würde ich sie überhaupt nicht kommentieren. Ich verwende Kommentare nur im Körper einer Methode / Funktion, wenn ich etwas extrem Schwieriges oder Unsichtbares tue - zwei Dinge, die ich vermeiden möchte. Geben Sie am Anfang der Methode einen kurzen Kommentar ein.
In diesem speziellen Beispiel würde ich die if-Anweisung nicht kommentieren - Sie wiederholen, was im Code gesagt wird.
Ich könnte einen Fall sehen, in dem der Testcode kompliziert ist:
%Vor%aber in diesem Fall würde ich zuerst versuchen, eine Methode mit einem aussagekräftigen Namen zu extrahieren:
%Vor%Nur wenn das nicht möglich wäre, würde ich dann den Test kommentieren.
Meine Empfehlung lautet "Nenne das Offensichtliche nicht".
Lesen wenn (! $ Anfrage) sagt - wenn keine Anfrage existiert. Ich brauche dazu keinen Kommentar.
Wenn Sie mehrere Checks haben (dies || (das & Amp; & Amp; auch dieses)), würde ich eine Methode erstellen, die einen Boolean mit dem Ergebnis zurückgibt. Dann ist Ihr Methodenname Ihr Kommentar, der normalerweise besser als ein tatsächlicher Kommentar ist.
Ich will nicht sagen, dass es nicht wichtig ist, aber es liegt meistens an der Vorliebe des Programmierers. Noch besser ist es, die Prädikate in der if-Anweisung so zu schreiben, dass sie ohne Kommentar lesbar sind.
Dies ist jedoch in einigen Sprachen einfacher als in anderen. Einige Sprachen verwenden beispielsweise Schlüsselwörter für die semantische Verneinung wie not , wodurch Prädikate einfacher zu lesen sind. Wenn der betreffende Leser ein Programmierer ist, der gut genug ist, sollte er in der Lage sein, die Logik eines allgemeinen Tests zu verarbeiten, ohne dass eine Annotation von Hand durchgeführt werden muss.
Bottom line: Verwenden Sie Ihre Diskretion.
In Ihrem Beispiel bevorzuge ich normalerweise den folgenden Stil:
%Vor% Ich möchte es in den Block if einfügen, damit es besser aussieht, wenn ein else oder else if vorhanden ist.
Lesen Sie das Buch Clean Code von Robert Martin.
Kommentare sollten nur verwendet werden, um Konzepte zu erklären, die der Code nicht selbst erklären kann.
Wenn ich Code-Kommentare schreibe, versuche ich entweder
Sehen Sie sich Code Complete an. McConnell hat ein großes Kapitel über das Kommentieren.
Ich würde das Buch jedem empfehlen, der Code schreibt.
Denken Sie daran: Es ist selten, dass Sie In-Line-Kommentare benötigen, um was der Code tut; Wenn Sie nicht einen besonders knorrigen Algorithmus erklären, sollte der Code diese Last ohne Kommentare übernehmen. (Und wenn dies nicht möglich ist, müssen Sie möglicherweise Ihre Variablennamen beschreibender machen.)
Allerdings können Kommentare, die erklären, warum der Code tut, was er tut, immens wertvoll sein. (Vorausgesetzt, es ist nicht blutig offensichtlich; wenn es ist, überspringen Sie einfach den Kommentar.)
Danach ist es wirklich eine Frage des persönlichen Geschmacks, obwohl ich Konsistenz befürworte. Wenn ich "if" -Bäume kommentiere, ziehe ich es persönlich vor, die Kommentare so einzufügen, dass sie mit der erklärten Klausel übereinstimmen:
%Vor%
Stellen Sie nur sicher, dass Ihre Kommentare ihre eigene Existenz rechtfertigen und der Rest ist Soße.
Ich mag es nicht, Code mit Kommentaren zu lesen. Der Code sollte einfach zu verstehen sein. Normalerweise kommentiere ich nur große, schwer verständliche Teile des Codes, nicht einzelne und triviale Zeilen.
Es liegt sehr am Programmierer. Ich werde zwei Tipps geben:
Geben Sie nicht das Offensichtliche an
Nehmen Sie das folgende Beispiel:
%Vor%Im obigen Fall wird der Code einfach durch den Kommentar dupliziert (ich weiß, dass es ein Beispiel war, aber ich möchte immer noch darauf hinweisen). Konzentrieren Sie sich darauf, zu klären, was im Code nicht offensichtlich ist. Auf der anderen Seite ...
Gehen Sie nicht davon aus, dass alle Entwickler wissen, was Sie wissen
Schau dir deinen Code an und stelle dir vor, dass du ein relativer Anfänger bist. Würdest du es verstehen? Wenn nicht, klären Sie mit Kommentaren.
Ich spreche den Verweis auf Code Complete: ein ausgezeichnetes Buch, das für Programmierer gelesen werden sollte.
Es gibt einige Dinge, die ich im Auge behalten würde:
Wiederhole den Code nicht : erkläre allgemein, was er tut.
Niemals davon ausgehen, dass etwas offensichtlich ist ; erklären und erklären Sie den Code.
Verwenden Sie Funktionen, um Ihre Bedeutung zu verdeutlichen , indem Sie den Namen in Beziehung setzen mit dem, was getan wird.
Niemals davon ausgehen, dass der Code selbsterklärend ist - auch wenn es sein sollte. Am wichtigsten ist, dass Sie niemals davon ausgehen, dass ein bestimmter Code "Idiom" von jemandem gelesen wird, der ihn versteht: Erklären Sie, was der Code macht.
Wie jemand sagte, führe nicht mit dem Negativ, wenn du kannst: Ich hatte eine Programmierklasse, in der unter keinen Umständen eine negative IF erlaubt war. Wenn Sie wirklich feststecken, können Sie Ihre Muttersprache (wie Englisch) zu Ihrem Vorteil verwenden. Statt:
%Vor%Man kann sagen:
%Vor%Mit Ihrem Beispiel würde ich mit so etwas gehen (wenn ich das richtig verstehe):
%Vor%Ich würde auch hinzufügen: keine Kommentare in Boxen . Eine "Box" ist schwer zu pflegen und hält Schritt. Man verbringt mehr Zeit damit, die "Box" zu reparieren, anstatt die Kommentare aktuell zu halten.
Das Beispiel if-Anweisungen ist einfach genug, um keine Kommentare zu rechtfertigen. Übermäßiges Kommentieren kann gefährlich sein, da dann nicht nur der Code, sondern auch die Kommentare gepflegt werden müssen. Für komplexe if-Anweisungen haben Sie die richtige Idee - halten Sie einen Kommentar direkt über der if-Anweisung.
Ich stimme mit neil überein, für dieses Beispiel ist es sowieso ziemlich offensichtlich, dass Sie prüfen, ob eine Anfrage nicht existiert. Wenn Sie viele Kommentare eingeben, kann dies dazu führen, dass Ihr Code weniger lesbar wird. (d. h. jede Zeile oder jede andere Codezeile kommentieren)
Ich stimme Evan zu - schreibe deinen Code so, dass er lesbar ist. Angenommen, Sie haben komplizierten Code, der kommentiert werden muss, verwende ich und bevorzuge die erste Option, die gut als lesbarer Text fließt.
Kommentare sollten Code erklären, der nicht klar ist. In den meisten Fällen sollte Code, der nicht klar ist, neu geschrieben werden, um klar zu sein. In Ihrem Beispiel sehe ich keinen Bedarf für einen Kommentar. So können Sie Ihre Kommentare aufschreiben, indem Sie den Code besser lesbar machen, sodass Sie keine Kommentare benötigen.
Wenn sie notwendig sind, sollten sie nicht einfach Pseudo-Code sein, sondern sollten Informationen bereitstellen, die der Leser nicht sofort verfügbar hat. Ein Beispiel könnte ein Kommentar bei einer "neuen" Anweisung sein, die angibt, wo Speicher freigegeben wird.
Wenn Ihre Variablen gut benannt sind, sollte Ihre if-Anweisung ziemlich selbst erklärend sein.
Auch bei einigen "strategischen" Kommentaren sollte alles plain english sein.
Sehen Sie sich in diesem Dokument die Definition von "taktischen" und "strategischen" Kommentaren an Ссылка
Siehe diese ähnliche / identische Frage: Wo Kommentare in ein IF THEN ELSE-Konstrukt geschrieben werden
Benennen Sie Ihre Variablen / Methoden so, dass ein Kommentar trivial wäre.
Wenn Sie viele komplexe Bedingungen in Ihrem if haben, dann extrahieren Sie diese Bedingung zu einer booleschen Funktion / Methode, die klar erklärt, was es macht.
Wenn Sie Ihre Bedingungen kommentieren müssen, sind Sie wahrscheinlich auf dem Weg zum Pfeil-Anti-Muster .
Verwenden Sie das Refactoring von Methoden , um dabei zu helfen. Stellen Sie sicher, dass Ihre Methoden / Funktionen auf derselben Abstraktionsebene gekapselt sind. Polymorphismus wird Ihnen erlauben, Conditionals ganz loszuwerden. Es ist besser, weil das Verhalten zur Laufzeit dynamisch bestimmt wird. Es ist eine Sache weniger, die Sie programmieren müssen (und pflegen).
Mir ist klar, dass es in Ihrem konkreten Beispiel nicht gilt, aber als Pedant muss ich sagen: Wenn möglich, führen Sie nicht mit dem negativen Fall. Das ist schwieriger zu lesen, egal was der Kommentar ist. Im Allgemeinen stimme ich zu, dass der Test ohne Kommentar klar sein sollte, oder Sie möchten ihn zu einer sinnvoll benannten Methode extrahieren.
Wie bereits gesagt, ist Ihr Beispiel vielleicht ein bisschen zu einfach, um wirklich einen relevanten Kommentar dazu zu haben, aber hier sind ein paar allgemeine Vorschläge:
ist normalerweise leichter "positive" Bedingungen als Negationen zu lesen (keine Bedingung)
zögern Sie nicht, Methoden zu extrahieren, die einen detaillierten Namen haben, der die Absicht kommuniziert und somit die Notwendigkeit einiger der Kommentare vermeidet. In Ihrem Fall, sagen Sie, erstellen Sie:
%Vor%Aber auch hier brauchen wir ein passenderes Beispiel, in Ihrem Fall ist es vielleicht ein Overkill
muss lauten:
Tags und Links language-agnostic comments