Citation:
Envoyé par
Pyramidev
L'inconvénient de morceler en sous-fonctions, c'est qu'il faut faire des aller-retours dans le code si on veut voir l'implémentation de ces sous-fonctions.
J'hésite entre :
- vous ne connaissez pas les IDEs ? Outils super pratiques qui permettent en général de naviguer dans le code
et
- pourquoi voir l'implémentation ? Si vous trouvez en Python print() ou en Java System.out.println() (ou l'équivalent dans d'autres langages), avez vous l'envie de voir l'implémentation ? Donc pourquoi y aller pour filterOffensiveWords() ?
Citation:
Résumer en quelques mots ce que fait une fonction ou ce que représente une classe, sauf si le nom de la fonction ou de la classe est déjà un résumé satisfaisant.
Le rôle du résumé est d'éviter d'obliger le lecteur à plonger dans le code s'il a besoin d'une information plus précise que le nom de la fonction ou de la classe mais pas forcément aussi précise que le code.
N'est-ce pas plutôt de la documentation que du commentaire ça ?
Citation:
Avertir sur les dangers d'une certaine fonction ou classe. Exemple : Attention, le bogue machin du ticket n°XXXX n'a pas encore été corrigé.
Auparavant, tu écris toi même :
Citation:
L'inconvénient des commentaires, c'est de risquer de ne pas être à jour par rapport au code.
Quand le ticket sera corrigé, qui ira mettre à jour les commentaires ? Quand quelqu'un relira cette partie, qui ira vérifier si le ticket a été fermé ?
Citation:
Écrire parfois quelques "rappels" techniques si le lecteur a des chances de ne pas les avoir. Cela rejoint d'une certaine manière ce que disait BugFactory, mais ça ne s'applique pas qu'aux stagiaires. Cela s'applique aussi si on fait appel à des subtilités d'un langage ou d'une bibliothèque.
Et là aussi, le commentaire sert à compenser une erreur de staffing…
Citation:
Mettre en évidence qu'un certain détail d'implémentation ne fait pas partie de l'interface.
Par exemple, dans une certaine classe, l'implémentation actuelle utilise un certain type de tableau associatif sous forme d'arbre binaire de recherche qui trie les éléments dans l'ordre des clés, mais l'implémentation future pourrait utiliser une table de hashage sans ce tri. Alors, dans l'interface de la classe, il vaut mieux avertir sous forme de commentaire : attention, ne vous reposez pas sur l'hypothèse que les éléments sont triés dans l'ordre des clés, car ça pourrait changer plus tard.
Là je cite l'exemple car en lui même il concerne quelque chose qui relève de la documentation.
Citation:
Aider l'utilisateur qui explore le code avec des commentaires de type "voir aussi telle fonction ou telle classe". Par exemple, quand il y a plusieurs fonction similaires (mais différentes), ce genre de commentaire aide l'utilisateur à trouver la bonne fonction à appeler.
Cette information là n'a pas sa place dans un commentaire mais la documentation.