PHP-Code kommentiert kleine Details

Codekommentare sind wichtiger als der Code selbst. Ich möchte Neulinge warnen, dass sie es sich zur Gewohnheit machen müssen, Kommentare zu schreiben, sonst schaden sie nur anderen und nützen sich selbst nicht. Hier sind einige Möglichkeiten, um sicherzustellen, dass die Kommentare, die Sie in Ihren Code schreiben, freundlich sind: „5 Dos und 3 Don’ts“
1. Wiederholen Sie nicht, was der Leser bereits weiß (×)

Es besteht keine Notwendigkeit, Kommentare zu schreiben, wenn Sie die Funktion allein durch einen Blick auf den Methodennamen und den Code erkennen können,

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

2. Kommentieren Sie die Begründung und den Verlauf aus (√)

Wenn die Geschäftslogik im Code in Zukunft möglicherweise aktualisiert oder geändert werden muss, wenden Sie sich bitte an uns sollte Kommentare 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++) {
  ...
}

3. Schreiben Sie keine sehr langen Kommentare in derselben Zeile(×)

Nichts geht über Ziehen. Die horizontale Bildlaufleiste zum Lesen von Kommentaren ist für Entwickler noch ärgerlicher. 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
}

4. 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;
    }
  };
}

5. Fügen Sie keine unnötigen Kommentare hinzu, um Kommentare zu erhalten (×)

Ü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
}

6. Kommentare müssen korrekt geschrieben sein (√)

Kommentieren Sie das nicht Code Entschuldigungen für Rechtschreibfehler. 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!
7. Mehr üben (√)
Ü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.
8. Überprüfen Sie die Kommentare anderer Personen (√)
Während der Codeüberprüfung neigen wir dazu, die Überprüfung von Hinweisen zu ignorieren. 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.
9. Eine wesentliche Zusammenfassung dessen, was Sie über Kommentare wissen müssen

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.