Clean Code verstehen: Kommentare ⚡️

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 untersuchen, wann man Kommentare verwendet, wann man sie vermeidet und wie man wertvolle Kommentare in JavaScript-Code schreibt.

---

?Wann sollten Kommentare vermieden werden?

1. Offensichtlicher Code:

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 lesbarer zu machen.

2. Irreführende Kommentare:

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.

3. Auskommentierter Code:

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.

---

---

? Wann Kommentare verwendet werden sollten

1. Klärung der Absicht:

Wenn ein Code 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 liefert wertvollen Kontext für zukünftige Entwickler.

2. Rechtliche Hinweise:

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.

3. Begründung einer Entscheidung:

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.

4. Öffentliche APIs:

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.

---

---

? Hilfreiche Kommentare schreiben

• Seien Sie klar und prägnant: Kommentare sollten unkompliziert und auf den Punkt kommen. 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 vertraut ist, der den Code liest.

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

---

---

Fazit ✅

Während Kommentare hilfreich sein können, lehrt uns der Clean Code, dass sie sparsam und zielgerichtet verwendet 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!