Verbesserung der Lesbarkeit mit Kommentaren

Der Schlüssel zum Schreiben guter Kommentare besteht darin, "warum" zu erklären, anstatt nur "was getan wurde", um die Lesbarkeit des Codes zu verbessern. 1. Kommentare sollten logische Gründe erklären, wie z. B. Überlegungen für die Wertauswahl oder -verarbeitung; 2. Verwenden Sie Absatz -Kommentare für komplexe Logik, um die Gesamtidee von Funktionen oder Algorithmen zusammenzufassen. 3. Wenn Sie die Kommentare regelmäßig beibehalten, um die Konsistenz mit dem Code zu gewährleisten, irreführend und gegebenenfalls veraltete Inhalte zu löschen; V.

Egal wie gut der Code geschrieben ist, wenn niemand ihn verstehen kann, wird er nutzlos sein. Das Schreiben von Kommentaren ist kein unnötiger Schritt, sondern es anderen (einschließlich ihres zukünftigen Selbst), Ihre Ideen schneller zu verstehen. Insbesondere in Projekten, bei denen mehrere Personen zusammenarbeiten oder langfristige Wartungen zusammenarbeiten, sind Annotationen der direkteste Weg, um die Lesbarkeit zu verbessern.

Kommentare sollten "Warum" erklären, nicht nur "Was hat es getan"

Was tun viele Menschen beim Schreiben von Kommentaren gewohnheitsmäßig wiederholt Code, wie z. B.:

 # Variable x auf 5 festlegen
x = 5

Diese Art von Kommentar ist tatsächlich nutzlos. Was wirklich nützlich ist, ist, die Logik hinter diesem Code zu erklären, z. B. warum Sie diesen Wert auswählen oder warum Sie auf diese Weise damit umgehen.

Zum Beispiel:

 # Verwenden Sie 5 als Standardwert, da die minimale Eingabe 5 beträgt
x = 5

Diejenigen, die so lesen, werden wissen, dass dies nicht beiläufig geschrieben ist, sondern einen bestimmten Grund hat. Sagen Sie nicht nur was Sie getan haben, sondern machen Sie klar, warum Sie es getan haben.

Fügen Sie Absatzkommentare in komplexe Logik hinzu

Einige Funktionen oder Algorithmen haben viel Logik, und es ist leicht, verwirrt zu werden, wenn Sie den Code direkt betrachten. Zu diesem Zeitpunkt können Sie zu Beginn eine kurze Erklärung schreiben, um die Gesamtidee klar zu erklären.

Zum Beispiel ein Code, der sich mit der Datenreinigung befasst:

 # Datenreinigungsschritte:
# 1. Entfernen Sie Ausreißer (Werte über die Dreifache der Standardabweichung)
# 2. Verwenden Sie die Vorwärtspolsterung für fehlende Werte# 3.
    ...

Auf diese Weise kann jemand den allgemeinen Prozess dieses Codes kennen, indem er ihn scannt, und es müssen nicht nacheinander erraten. Besonders für diejenigen, die gerade übernommen wurden, ist diese strukturierte Annotation sehr freundlich.

Notizen sollten auch regelmäßig aufrechterhalten werden. Lassen Sie sie also nicht irreführend werden

Viele Menschen kümmern sich nicht mehr um Kommentare, nachdem Sie den Code geschrieben haben. Infolgedessen wurde der Code für mehrere Runden geändert, und die Kommentare sind immer noch gleich. Diese Situation ist schlimmer als keine Kommentare zu schreiben, weil sie andere irreführen kann.

Es wird empfohlen, die Kommentare zu aktualisieren, wenn die Schlüssellogik geändert wird, auch wenn einfach der Wortlaut angepasst wird. Wenn Sie feststellen, dass ein Kommentar nicht mehr mit dem Code übereinstimmt, zögern Sie nicht. Es ist besser, es zu löschen, als es irreführend zu lassen.

Betrachten Sie außerdem die folgenden Praktiken, um die Qualität der Annotation aufrechtzuerhalten:

• Überprüfen Sie bei der Überprüfung der PR, ob relevante Kommentare aktualisiert werden müssen
• Notieren Sie die öffentliche Logik in Dokumenten oder Wikis und vermeiden Sie die Verwendung von Code -Kommentaren, um die komplexe Logik zu erklären
• Löschen offensichtlich veraltete und bedeutungslose Kommentare wie # TODO: 这个地方需要优化wurde jedoch nicht geändert

Grundsätzlich ist das. Notizen sind nicht so viel geschrieben, wie Sie möchten, sondern sie müssen genau und klar geschrieben werden. Wenn es gut verwendet wird, ist es die Bedienungsanleitung des Codes. Wenn es schlecht verwendet wird, wird es zu Geräusch.

Das obige ist der detaillierte Inhalt vonVerbesserung der Lesbarkeit mit Kommentaren. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!