Codekommentare werden in der Softwareentwicklung als notwendig erachtet, aber das Clean Code-Buch schlägt vor, dass Code selbsterklärend sein sollte, ohne dass Kommentare erforderlich sind.
Wir werden untersuchen, wann man Kommentare verwendet, wann man sie vermeidet und wie man wertvolle Kommentare in JavaScript-Code schreibt.
Kommentare sollten nicht dazu verwendet werden, zu erklären, was der Code tut, wenn dies bereits aus dem Code selbst hervorgeht.
Zum Beispiel:
// Increment the counter by 1 counter++; // Check if the user is an admin if (user.isAdmin()) { // ... }
In diesen Fällen sind die Kommentare überflüssig, da der Code selbsterklärend ist. Anstatt unnötige Kommentare hinzuzufügen, konzentrieren Sie sich darauf, Ihren Code besser lesbar zu machen.
Ein Kommentar, der nicht mit dem Code übereinstimmt, kann zu Verwirrung und Fehlern führen. Wenn Sie den Code aktualisieren, aber vergessen, den Kommentar zu aktualisieren, wird er irreführend:
// Initialize user object let user = new AdminUser(); // Actually, it's creating an AdminUser, not a regular user
Hier ist der Kommentar irreführend und könnte jemanden, der den Code später liest, verwirren. Es ist besser, entweder den Kommentar zu entfernen oder sicherzustellen, dass er den Code genau wiedergibt.
Alten Code auskommentiert zu lassen, ist eine häufige schlechte Praxis. Es überfüllt die Codebasis und kann verwirren:
// Old code // let data = fetchDataFromAPI(); // New code let data = fetchDataFromDatabase();
Anstatt alten Code auskommentiert zu lassen, verwenden Sie Versionskontrollsysteme wie Git, um Codeänderungen zu verfolgen. Dadurch bleibt Ihre Codebasis sauber und fokussiert.
Wenn ein Codeabschnitt eine komplexe Logik aufweist oder eine Problemumgehung beinhaltet, kann ein Kommentar klären, warum der Code existiert:
// Using a workaround for browser-specific bug in IE11 if (isIE11()) { fixIEBug(); }
Der Kommentar erklärt, warum der Code notwendig ist, und bietet künftigen Entwicklern wertvollen Kontext.
Manchmal sind Kommentare aus rechtlichen Gründen erforderlich, beispielsweise um Urheberrechtsinformationen oder Lizenzdetails anzugeben:
/* * Copyright (c) 2024 MyCompany. All rights reserved. * Licensed under the MIT License. */
Diese Kommentare sind unerlässlich und sollten gemäß den Anforderungen der Lizenzierung Ihres Projekts enthalten sein.
Wenn eine bestimmte Entscheidung im Kodex begründet werden muss, kann ein Kommentar hilfreich sein:
// Using a binary search because the list is sorted let index = binarySearch(sortedArray, target);
Dieser Kommentar erklärt, warum eine binäre Suche gewählt wurde, und gibt Einblick in die Gründe für die Implementierung.
Beim Schreiben öffentlich zugänglicher APIs können Kommentare dabei helfen, deren Verwendung zu dokumentieren, insbesondere in JavaScript, wo Sie möglicherweise nicht über integrierte Dokumentationstools verfügen:
/** * Calculates the area of a rectangle. * @param {number} width - The width of the rectangle. * @param {number} height - The height of the rectangle. * @returns {number} The area of the rectangle. */ function calculateArea(width, height) { return width * height; }
In diesem Fall bietet der Kommentar eine klare Dokumentation zur Verwendung der Funktion, was besonders für andere Entwickler nützlich ist, die sie möglicherweise verwenden.
Seien Sie klar und prägnant:Kommentare sollten unkompliziert und auf den Punkt gebracht sein. Vermeiden Sie es, langwierige Erklärungen zu schreiben, die anhand des Codes selbst leicht verständlich sind.
Vermeiden Sie Fachjargon:Verwenden Sie eine leicht verständliche Sprache und vermeiden Sie Fachjargon, der möglicherweise nicht jedem, der den Code liest, vertraut ist.
Kommentare aktualisieren:Aktualisieren Sie Ihre Kommentare immer, wenn sich der Code ändert. Eine gute Faustregel lautet: Wenn Sie den Code berühren, überprüfen Sie die Kommentare.
Konzentrieren Sie sich auf das Warum, nicht auf das Was:Gute Kommentare erklären, warum eine bestimmte Entscheidung getroffen wurde, anstatt zu beschreiben, was der Code tut:
// We need to sort the array before performing the search array.sort();
Dieser Kommentar erklärt, warum eine Sortierung vor der Suche notwendig ist, und fügt wertvollen Kontext hinzu.
Obwohl Kommentare hilfreich sein können, lehrt uns der Clean Code, dass sie sparsam und zielgerichtet eingesetzt werden sollten.
Ziel ist es, Code zu schreiben, der so klar ist, dass Kommentare fast überflüssig werden.
Wenn Kommentare erforderlich sind, stellen Sie sicher, dass sie aussagekräftig und genau sind und jedem, der Ihren Code liest, einen Mehrwert bieten.
Indem Sie diese Richtlinien befolgen, verbessern Sie nicht nur die Qualität Ihres Codes, sondern machen es auch für andere (und Sie selbst) einfacher, ihn zu verstehen und zu warten.
Viel Spaß beim Codieren!
Das obige ist der detaillierte Inhalt vonClean Code verstehen: Kommentare ⚡️. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!
