par
naholyr » 23 avr. 2008, 17:45
Chez nous les commentaires ne sont pas une question de goût ou une option : les doc-comments sont absolument obligatoires.
On le fait (et on l'impose) pour plusieurs raisons :
- L'auto-complétion dans les "vrais" éditeurs
- La génération automatique de la documentation de l'API (qui est souvent un livrable qu'on fait payer au client, donc les commentaires se doivent d'apporter quelque chose de concret dans la compréhension, et surtout d'être justes)
- La compréhension du code ? C'est bien gentil mais quand on réutilise une API on n'a pas à aller fouiller dans le code pour comprendre comment ça fonctionne, quel est la classe retournée, etc... On doit pouvoir se contenter de lire les doc-comments.
En revanche on est moins chiant pour les commentaires "inline". Du moment que la fonction est testée et réagit comme la doc le prévoit, finalement l'intérieur ne compte pas tant que ça (c'est un autre discours quand on parle performances bien sûr). De toute façon je milite pour que les fonction dont le corps dépasse les 25 lignes se comptent sur les doigts d'une main (c'est con de dire 25 lignes comme ça arbitrairement, mais au moins comme ça, ça pose une limite et ça force les développeurs à refléchir à la factorisation de leur code). Donc sur si peu de code les commentaires "inline" sont généralement inutiles.
Ensuite pour répondre à la question initiale : aucune fonction ou méthode ne doit pas être précédée d'un bloc de commentaires. Donc là encore on préfèrera un copier-coller à une absence de commentaire. L'idéal étant de ne rappeler que les @params, @throws et @return, et de mettre un @see vers la méthode parent pour avoir la documentation détaillée.
Là encore c'est pour plusieurs raisons :
- Toujours pour l'auto-complétion, l'éditeur ira toujours chercher les doc-comments de la méthode réelle, il n'ira pas chercher la doc de la méthode parente s'il n'y a pas de doc dans la classe fille. Ce serait conceptuellement faux de toute façon : ce n'est pas parce qu'on redéfinit une méthode qu'elle fait forcément la même chose chez la fille que chez la mère, partir de ce principe serait une erreur.
- S'il y a implémentation (interface) ou redéfinition (héritage) c'est qu'il y a une modification par rapport à la classe mère, et donc il doit y avoir un commentaire qui au moins explique le pourquoi de cette redéfinition ou la spécificité de cette implémentation, et au passage on rajoute toujours les @params & @return pour plus de "complétude" dans le commentaire tout simplement.
Ceux qui n'aiment pas les commentaires ont en général deux arguments massue :
- Ça fait perdre du temps : Non, ça en fait gagner grâce à une auto-complétion parfaitement opérationnelle, et grâce au fait que quand je reviendrai sur mon code dans 6 mois je n'aurai plus à lire le code (et d'ailleurs je m'en cognerai comme de l'an 40 de comment la fonction marche, vu que tout ce que j'ai à savoir c'est ce qu'elle prend en entrée et ce qu'elle me retourne).
- Ça tue les perfs : C'est de l'ordre de la nano-seconde mais il est vrai que ça peut augmenter légèrement la RAM utilisée par le serveur. Mais c'est vraiment infinitésimal par rapport à la même surcharge causée par tous ces espaces inutiles que sont l'indentation. Donc soit on va jusqu'au bout et on n'indente carrément plus, soit on accepte que les commentaires ne jouent pas sur les perfs par rapport à un script aéré "classique". Et avant déploiement un petit "php -w" sur tous vos scripts ne fait pas de mal (on gagne vite quelques Ko de RAM par exécution, et même quelques millisecondes des fois).
- Ça sert à rien car le code est clair : Ah mon Nagol, si t'existais pas faudrait t'inventer
je te souhaite de reprendre le code de quelqu'un qui pense comme toi, et qui lui aussi trouve qu'il code très bien. Sauf qu'en fait vous codez pas pareil, et lui il appelle pas ses variables avec les même noms que toi, et mine de rien tu mets quand-même 5 à 10 minutes pour comprendre cette petite fonction là, que si elle avait été commentée ça aurait été aussi rapide que de lire 3 lignes
Chez nous les commentaires ne sont pas une question de goût ou une option : les doc-comments sont absolument obligatoires.
On le fait (et on l'impose) pour plusieurs raisons :
[list=1]
[*]L'auto-complétion dans les "vrais" éditeurs :)
[*]La génération automatique de la documentation de l'API (qui est souvent un livrable qu'on fait payer au client, donc les commentaires se doivent d'apporter quelque chose de concret dans la compréhension, et surtout d'être justes)
[*]La compréhension du code ? C'est bien gentil mais quand on réutilise une API on n'a pas à aller fouiller dans le code pour comprendre comment ça fonctionne, quel est la classe retournée, etc... On doit pouvoir se contenter de lire les doc-comments.[/list]
En revanche on est moins chiant pour les commentaires "inline". Du moment que la fonction est testée et réagit comme la doc le prévoit, finalement l'intérieur ne compte pas tant que ça (c'est un autre discours quand on parle performances bien sûr). De toute façon je milite pour que les fonction dont le corps dépasse les 25 lignes se comptent sur les doigts d'une main (c'est con de dire 25 lignes comme ça arbitrairement, mais au moins comme ça, ça pose une limite et ça force les développeurs à refléchir à la factorisation de leur code). Donc sur si peu de code les commentaires "inline" sont généralement inutiles.
Ensuite pour répondre à la question initiale : aucune fonction ou méthode ne doit pas être précédée d'un bloc de commentaires. Donc là encore on préfèrera un copier-coller à une absence de commentaire. L'idéal étant de ne rappeler que les @params, @throws et @return, et de mettre un @see vers la méthode parent pour avoir la documentation détaillée.
Là encore c'est pour plusieurs raisons :
[list=1]
[*]Toujours pour l'auto-complétion, l'éditeur ira toujours chercher les doc-comments de la méthode réelle, il n'ira pas chercher la doc de la méthode parente s'il n'y a pas de doc dans la classe fille. Ce serait conceptuellement faux de toute façon : ce n'est pas parce qu'on redéfinit une méthode qu'elle fait forcément la même chose chez la fille que chez la mère, partir de ce principe serait une erreur.
[*]S'il y a implémentation (interface) ou redéfinition (héritage) c'est qu'il y a une modification par rapport à la classe mère, et donc il doit y avoir un commentaire qui au moins explique le pourquoi de cette redéfinition ou la spécificité de cette implémentation, et au passage on rajoute toujours les @params & @return pour plus de "complétude" dans le commentaire tout simplement.[/list]
Ceux qui n'aiment pas les commentaires ont en général deux arguments massue :
[list]
[*][i]Ça fait perdre du temps[/i] : Non, ça en fait gagner grâce à une auto-complétion parfaitement opérationnelle, et grâce au fait que quand je reviendrai sur mon code dans 6 mois je n'aurai plus à lire le code (et d'ailleurs je m'en cognerai comme de l'an 40 de comment la fonction marche, vu que tout ce que j'ai à savoir c'est ce qu'elle prend en entrée et ce qu'elle me retourne).
[*][i]Ça tue les perfs[/i] : C'est de l'ordre de la nano-seconde mais il est vrai que ça peut augmenter légèrement la RAM utilisée par le serveur. Mais c'est vraiment infinitésimal par rapport à la même surcharge causée par tous ces espaces inutiles que sont l'indentation. Donc soit on va jusqu'au bout et on n'indente carrément plus, soit on accepte que les commentaires ne jouent pas sur les perfs par rapport à un script aéré "classique". Et avant déploiement un petit "php -w" sur tous vos scripts ne fait pas de mal (on gagne vite quelques Ko de RAM par exécution, et même quelques millisecondes des fois).
[*][i]Ça sert à rien car le code est clair[/i] : Ah mon Nagol, si t'existais pas faudrait t'inventer :lol: je te souhaite de reprendre le code de quelqu'un qui pense comme toi, et qui lui aussi trouve qu'il code très bien. Sauf qu'en fait vous codez pas pareil, et lui il appelle pas ses variables avec les même noms que toi, et mine de rien tu mets quand-même 5 à 10 minutes pour comprendre cette petite fonction là, que si elle avait été commentée ça aurait été aussi rapide que de lire 3 lignes :)[/list]
