Man kann sagen, dass Codekommentare wichtiger sind als der Code selbst. Hier sind einige Möglichkeiten, um sicherzustellen, dass die Kommentare, die du in deinem Code schreibst, freundlich sind:

Wiederhole nicht, was Leser bereits wissen

Kommentare, die nur angeben, was der Code tut, sind für uns nicht hilfreich.

// If the color is red, turn it green 
if (color.is_red()) { 
    color.turn_green(); 
} 

Kommentiere, um Begründungen und Historie zu erklären

Wenn die Geschäftslogik im Code später möglicherweise aktualisiert oder geändert werden muss, solltest du einen Kommentar hinterlassen.

/* The API currently returns an array of items 
even though that will change in an upcoming ticket. 
Therefore, be sure to change the loop style here so that 
we properly iterate over an object */ 
 
var api_result = {items: ["one", "two"]}, 
items = api_result.items, 
num_items = items.length; 
 
for(var x = 0; x < num_items; x++) { 
    ... 
}

Mach Inline-Kommentare nicht zu lang

Nichts ärgert Entwickler mehr, als die horizontale Bildlaufleiste zu ziehen, um Kommentare zu lesen. Tatsächlich werden die meisten Entwickler solche Kommentare ignorieren, weil sie wirklich unbequem zu lesen sind.

function Person(name) { 
    this.name = name; 
    this.first_name = name.split(" ")[0]; // This is just a shot in the dark here. If we can extract the first name, let's do it 
} 

Setze lange Kommentare über die Logik und kurze Kommentare danach

Kommentare können neben den Code gesetzt werden, wenn sie 120 Zeichen nicht überschreiten. Andernfalls solltest du den Kommentar direkt über die Anweisung setzen.

if (person.age < 21) { 
    person.can_drink = false; // 21 drinking age 
 
    /* Fees are given to those under 25, but only in 
    some states. */ 
    person.has_car_rental_fee = function(state) { 
        if (state === "MI") { 
            return true; 
        } 
    }; 
}

Füge keine unnötigen Kommentare hinzu, nur um des Kommentierens willen

Übermäßig wortreiche Kommentare können Verwirrung stiften. Vielleicht hat dir dein Lehrer in der Schule beigebracht, allen Anweisungen Kommentare hinzuzufügen, damit Entwickler besser verstehen. Aber das ist falsch. Wenn jemand das sagt, solltest du ihm sofort zwei kräftige Ohrfeigen geben. Code sollte sauber und prägnant gehalten werden, daran besteht kein Zweifel. Wenn dein Code Zeile für Zeile erklärt werden muss, dann ist ein Refactoring das, was du am meisten brauchst.

if (person.age >= 21) { 
    person.can_drink = true; // A person can drink at 21 
    person.can_smoke = true; // A person can smoke at 18 
    person.can_wed = true; // A person can get married at 18 
    person.can_see_all_movies = true; // A person can see all movies at 17 
    //I hate babies and children and all things pure because I comment too much 
}

Achte auf korrekte Rechtschreibung bei Kommentaren

Mach keine Ausreden für Rechtschreibfehler in Code-Kommentaren. Die IDE kann die Rechtschreibung für dich prüfen. Wenn sie diese Funktion nicht hat, dann lade dir ein Plugin herunter und erledige es selbst!

Übe viel

Übung macht den Meister. Versuche, einige nützliche Kommentare zu schreiben, und du kannst andere Entwickler fragen, ob deine Kommentare nützlich sind. Mit der Zeit wirst du nach und nach verstehen, was als freundliche Kommentare gilt.

Überprüfe die Kommentare anderer

Beim Code-Review neigen wir oft dazu, Kommentare zu ignorieren. Hab keine Angst, um mehr Kommentare zu bitten; du solltest Fragen stellen. Wenn jeder die gute Angewohnheit entwickelt, gute Kommentare zu schreiben, wird die Welt ein besserer Ort.

Zusammenfassung

Kommentare sind ein sehr wichtiger Teil des Entwicklungsprozesses, aber wir sollten nicht um des Kommentierens willen kommentieren. Kommentare sollten nützlich, prägnant sein und den Code ergänzen. Kommentare sollten nicht verwendet werden, um Code Zeile für Zeile zu erklären; stattdessen sollten sie verwendet werden, um Geschäftslogik, Begründungen und Auswirkungen auf die Zukunft zu erklären.