5 Do's und 3 Don'ts in Codekommentaren

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

Wiederholen Sie nicht, was der Leser bereits weiß

Kommentare, die klar erklären, was der Code tut, sind nicht hilfreich uns hilfreich.

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

Es sollten Kommentare abgegeben werden, um die Argumentation und den Verlauf zu erläutern

Wenn die Geschäftslogik im Code in Zukunft möglicherweise aktualisiert oder geändert werden muss, sollten Kommentare hinterlassen werden:)

/* 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++) {
  ...
}

Schreiben Sie keine sehr langen Kommentare in derselben Zeile

Nichts macht Entwickler wütender, als die horizontale Bildlaufleiste zu ziehen, um Kommentare zu lesen. Tatsächlich ignorieren die meisten Entwickler solche Kommentare, 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
}

Platzieren Sie lange Kommentare über der Logik und kurze Kommentare hinten

Kommentare können neben dem Code platziert werden, wenn sie 120 Zeichen nicht überschreiten. Andernfalls sollte der Kommentar direkt über der Aussage platziert werden.

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ügen Sie keine unnötigen Kommentare um der Kommentare willen hinzu

Überflüssige Kommentare können Verwirrung stiften. Vielleicht wurde Ihnen in der Schule beigebracht, alle Aussagen auszukommentieren, was den Entwicklern helfen würde, sie besser zu verstehen. Aber das ist falsch. Wenn jemand das sagt, geben Sie ihm sofort eine Ohrfeige. Es versteht sich von selbst, dass der Code sauber und prägnant gehalten werden sollte. Wenn Ihr Code eine zeilenweise Erklärung erfordert, ist die Umgestaltung das Wichtigste, was Sie tun müssen.

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
}

Kommentare sollten korrekt geschrieben sein

Machen Sie keine Ausreden für Rechtschreibfehler in Codekommentaren. Die IDE kann die Rechtschreibung für Sie überprüfen. Wenn Sie diese Funktion nicht haben, dann laden Sie das Plug-in herunter und machen Sie es selbst!

Übe immer mehr

Übung macht den Meister. Versuchen Sie, einige nützliche Kommentare zu schreiben, und fragen Sie andere Entwickler, ob Ihre Kommentare nützlich sind. Mit der Zeit lernen Sie, was einen freundlichen Kommentar ausmacht.

Um die Kommentare anderer Leute zu überprüfen

Bei der Überprüfung von Code ignorieren wir oft die Überprüfung von Kommentaren. Scheuen Sie sich nicht, um weitere Kommentare zu bitten, Sie sollten Fragen stellen. Wenn jeder die gute Angewohnheit entwickeln würde, gute Notizen zu schreiben, wäre die Welt ein besserer Ort.

Zusammenfassung

Kommentare sind ein sehr wichtiger Teil des Entwicklungsprozesses, aber wir sollten nicht um der Kommentare willen kommentieren. Kommentare sollten nützlich und prägnant sein und den Code ergänzen. Kommentare sollten nicht dazu verwendet werden, den Code Zeile für Zeile zu erläutern, sondern stattdessen zur Erläuterung der Geschäftslogik, Argumentation und Implikationen für die Zukunft.