Le code PHP commente les petits détails

On peut dire que les commentaires sur le code sont plus importants que le code lui-même. Je voudrais avertir les nouveaux arrivants qu'ils doivent développer l'habitude d'écrire des commentaires, sinon ils ne feront que nuire aux autres et ne bénéficieront pas à eux-mêmes. Voici quelques façons de vous assurer que les commentaires que vous écrivez dans votre code sont conviviaux. Pour résumer, ce sont « 5 à faire et 3 à ne pas faire »
1. Ne répétez pas le contenu que les lecteurs connaissent déjà ( ×)

Il n'est pas nécessaire d'écrire des commentaires si vous pouvez voir la fonction simplement en regardant le nom et le code de la méthode,

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

2. Commentez le raisonnement et l'historique (√)

Si la logique métier du code doit être mise à jour ou modifiée dans le à l'avenir, vous devriez laisser des commentaires :

/* 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. N'écrivez pas de très longs commentaires sur la même ligne(×)

Rien de tel que faire glisser la barre de défilement horizontale pour lire les commentaires est encore plus agaçante pour les développeurs. En fait, la plupart des développeurs choisissent d’ignorer ces commentaires car ils sont vraiment peu pratiques à lire.

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. Mettre les commentaires longs au dessus de la logique et les commentaires courts à la fin (√)

Des commentaires peuvent être placés à côté du code s'ils ne dépassent pas 120 caractères. Sinon, le commentaire doit être placé directement au-dessus de la déclaration.

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. N'ajoutez pas de commentaires inutiles pour le plaisir des commentaires (×)

Les commentaires superflus peuvent prêter à confusion. Peut-être qu'à l'école, on vous a appris à commenter toutes les déclarations, ce qui aiderait les développeurs à mieux comprendre. Mais c'est faux. Si quelqu’un dit cela, donnez-lui une gifle immédiatement. Il va sans dire que le code doit rester propre et concis. Si votre code nécessite une explication ligne par ligne, la chose la plus importante à faire est de le refactoriser.

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. Les commentaires doivent être correctement orthographiés (√)

Ne pas commenter code Excuses pour les fautes d’orthographe. L'EDI peut vérifier l'orthographe pour vous. Si vous ne disposez pas de cette fonction, téléchargez le plug-in et faites-le vous-même !
7. Pratiquez davantage (√)
La pratique rend parfait. Essayez d'écrire des commentaires utiles et demandez à d'autres développeurs si vos commentaires sont utiles. Au fil du temps, vous apprendrez ce qui constitue un commentaire amical.
8. Examinez les commentaires des autres (√)
Lors de la révision du code, nous avons tendance à ignorer la vérification de la note. N'hésitez pas à demander plus de commentaires, vous devriez poser des questions. Si tout le monde prenait la bonne habitude d’écrire de bonnes notes, le monde serait meilleur.
9. Un résumé essentiel de ce qu'il faut savoir sur les commentaires

Les commentaires sont une partie très importante du processus de développement, mais nous ne devrions pas commenter pour le plaisir de commenter. Les commentaires doivent être utiles, concis et compléter le code. Les commentaires ne doivent pas être utilisés pour expliquer le code ligne par ligne, mais plutôt pour expliquer la logique métier, le raisonnement et les implications pour l'avenir.