Écrivez-vous des commentaires en 2e ou 3ème personne? ou P> // goes somewhere and does something (3rd person comment)
6 Réponses :
définitivement style 3ème personne.
J'ai souvent tendance à parler de style médecin:
Un conseil utile: essayez de garder chaque commentaire aussi autonome que possible. Par exemple, ce formulaire:
// First, mumble the frabbitz. blah blah // Second, foobar the quux blah blah
Je parle parfois en 1ère personne, comme ce
Cela peut dépendre du nombre de personnes édictant le code et dans quel but. Dans mon propre code (qui est néanmoins de la vue publique), je me sentirai peut-être libre d'ajouter des commentaires personnels, peut-être utiliser "I '. Dans un projet communal, les commentaires devraient viser un style commun et «je» peut être hors de propos.
Notez que les commentaires sont fragiles et de nombreuses autorités modernes (par exemple le code de nettoyage) suggèrent que les fonctions et les champs devraient porter des noms significatifs. Mais, bien sûr, il existe de nombreux endroits où des commentaires explicatifs sont encore vitaux.
Mon point de vue est que vous devriez simplement utiliser le style que vous vous sentez le plus à l'aise.
Les commentaires intégrés sont destinés à être lus par vous et d'autres développeurs essayant de comprendre les détails de votre mise en œuvre de votre code. Tant qu'ils sont clairs et intelligibles, il importe si elles sont un peu inhabituelles, la grammaire est un peu pauvre, ou il y a quelques erreurs d'orthographe. Les gens qui lisent cela devraient être au-delà de se soucier de telles choses.
Les commentaires extraits pour former une documentation API méritent un peu plus d'attention aux Nexéties du style, de la grammaire et de l'orthographe. Mais même ici la précision et l'exhaustivité sont beaucoup plus importants.
Je dois être en désaccord avec le commentaire sur les commentaires. Pour moi, des commentaires faciles à lire sont ceux qui sont bien écrits - ce qui signifie une bonne grammaire, une bonne orthographe et une bonne ponctuation.
Hé, regarde, je trouve aussi irritant de voir une mauvaise grammaire orthographe, etc. dans les commentaires. Mais je vais supporter cela sans plainte. Très peu de développeurs sont capables de produire une prose pétillante. Et même s'ils étaient, il y a plus de choses productives qu'ils pourraient faire avec leur temps que de polir leurs commentaires.