Commentaires – Coder proprement

Le meilleur commentaire est celui que vous pouvez éviter d’écrire.

Les “bons” commentaires

– légaux : déclaration de licence
– informatifs : décrire un cas particulier ou complexe (expressions régulières)
– d’explications de décision
– de clarifications : dans les cas où on utilise une librairie ayant des fonctions mal nommées
– d’avertissements
– TODO
– d’amplifications : quand une instruction paraît anodine mais en fait ne l’est pas
– documentations

Les “mauvais” commentaires

– mystiques : seul l’auteur comprend ce qu’il a écrit ou nous fait poser des questions
– redondants/inutiles : le code est plus clair que le commentaire
– trompeurs : une erreur d’explication par rapport au code
– obligatoires : mettre la description des paramètres alors que l’argument parle de lui même
– journalisations : liste des modifications en début de fichier, inutile depuis l’arrivée des systèmes de gestion de versions
– marqueurs de position : ceux qui visuellement délimite le code entre groupes/type de fonctions
– d’accolade fermante : } //end main
– de signature : quand on dit que ce code a été écrit par quelqu’un
– code en commentaire : le code soit il est présent soit on le supprime, mais on le met pas en commentaire
– information non local : explication du port par défaut dans une méthode setPort
– trop d’informations : un extrait d’une RFC
– en entête de fonction : pas besoin si on nomme correctement la fonction