Lisant une réponse que l'on m'a fait sur ce forum, je me suis souvenu d'une question que je voulais poser dans le passé, et je l'avais oubliée :

Dans le cas d'une interface, dans laquelle on définit les méthodes à implémenter.

Quel intérêt de commenter à nouveau ces méthodes dans les classes l'implémentant ? C'est un peu comme pour le code, ça fait de la redondance non ?

On commente, on commente pas ?

moi je suis tout simplement contre le commentaire.

un code bien indenté et écrit de façon logique et générique doit pouvoir être lu comme on lirait un roman, et cela sans aucun commentaires. Bien sûr il est nécessaire de tenir compte de l'auditoire possible de ton code et d'y adapter ce raisonement.

De mon côté, je suis pour. Rien n'empêche le lecteur de lire seulement le code et de faire abstraction des commentaires, mais pour une vue générale d'une application, passer par un générateur de documentation en parallèle des merise ou UML me paraît assez pratique.

Cela dit, ton raisonnement se tient assez bien d'un programmeur à l'autre. Merci de ta réponse, mais je ne suivrai pas le conseil sous ce raisonnement là.

Et puis il y a parfois des subtilités faciles à comprendre quand on est plongé dans le code depuis plusieurs heures et qu'il est difficile de retrouver rapidement plusieurs mois plus tard quand il y a une petite maj à faire.
Bref, je faisais peu de commentaires mais maintenant je documente tout ce qui n'est pas basique.

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 :

1. L'auto-complétion dans les "vrais" éditeurs
2. 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)
3. 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 :

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.
2. 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

• Ç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

Merci

Ceci dit, je ne suis pas d'accord je ne passe jamais longtemps à comprendre un code quelconque mais le mien même des années après je le relis sans aucun soucis, maintenant n'oublies pas que j'ai bien précisé qu'il fallait adapter le raisonement à l'auditoire, et donc aux personnes avec qui on travaille, alors tu me diras et les nouveaux arrivants? Et bien c'est simple soit ils ont une logique suffisante pour accrocher le wagon soit ils auront des soucis pour s'y retrouver et à la limite ca n'est pas de mon ressort. Toujours est-il que je n'ai pas eu jusqu'ici d'expérience problématique avec d'autres codeurs

naho, t'as oublié deux arguments anti-commentaires :
- pfiouhou, la flemme
- dans un projet, si tu ne commentes pas, ils sont obligés de te garder parce que t'es le seul à comprendre ton code

Un autre argument contre c'est que:

- Ca rend le code sale, carrément et diminue la lisibilité générale du code

- dans un projet, si tu ne commentes pas, ils sont obligés de te garder parce que t'es le seul à comprendre ton code

J'espère que personne ne pense ça, parce qu'au contraire dans un projet si un dév ne commente pas, je me sens obligé de ne pas le garder

naho, t'as oublié deux arguments anti-commentaires :
- dans un projet, si tu ne commentes pas, ils sont obligés de te garder parce que t'es le seul à comprendre ton code

Je connais quelqu'un qui s'est rendu indispensable durant 14 ans en partie grâce à ça Il vient juste de perdre le marché cette année - plusieurs centaines d'applications sur toute la france pour des grands comptes - faute de mise à jour pour une solution internet. Tant que les clients étaient contents il ne s'est pas trop pris la tête : son programme fonctionne toujours en 16 bits ... mais bon ça passe encore même sous vista.
Il devrait pas être loin de figurer dans le livre des records : 14 ans sans mise à jour technique majeure, presque uniquement des mises à jours fonctionnelles

Y'a des reccords beaucoup plus impressionnants dans le monde bancaire et les assurances à mon avis

bref,

je commente tout ...

hu hu

merci à vous.

ouckileou nous met d'accord :

Dans le meilleur des mondes on aurait bien le temps de faire les choses, de faire de la doc, tout bien tout ça, mais on est pas chez les bisounours non plus.

De toute façon ya pas le temps de commenter
(quoi je détourne ses propos ? )

Alors ça vraiment c'est...

Alors ça vraiment c'est...

comme un discours politique