Dans le grand débat : Qu'est-ce qu'un code "propre" selon vous ?, tous le monde n'est pas d'accord sur le fait que commenter son code rende celui plus exploitable/lisible.
Quel est votre avis ?
Inscrivez-vous gratuitement
pour pouvoir participer, suivre les réponses en temps réel, voter pour les messages, poser vos propres questions et recevoir la newsletter
Oui
Non
Discussion :
Faut-il commenter son code source pour le rendre plus lisible et maintenable ?
Dans le grand débat : Qu'est-ce qu'un code "propre" selon vous ?, tous le monde n'est pas d'accord sur le fait que commenter son code rende celui plus exploitable/lisible.
Quel est votre avis ?
En fait ça ne se discute pas trop. La question n'est pas de savoir s'il faut commenter, mais plutôt comment et en quelle quantité. Il peut peut-être y avoir des cas extrêmement exceptionnel… menfinbon il me semble que même là les commentaires restent pertinents.
pour moi oui mais avec modération ....
lors de cas de test bien tordu, issu du métier par exemple il est nécessaire d'avoir une petite note pour nous éclairer
C'est un peu abuser ce sondage. Telle qu'est posée la question, je vois difficilement comment on peut répondre non.
Pour une démonstration/exemple/tutoriel/cours/etc oui il faut commenter le code c'est évident et vraiment utile.
En production par contre c'est différent. On ne peut plus appeler cela un commentaire puisqu'on s'en sert aussi pour l'automatisation des tests et/ou de la documentation voir d'autres choses encore.
Soit cela sonne comme 'complétement déréglée' lorsque chacun mets à sa sauce le type de commentaire qu'il lui fait plaisir et la qualité du document de code se dégrade avec le temps.
Qui n'a jamais lu un commentaire incompréhensible voir douteux sur un projet dans lequel il est entré et qui existe depuis belle lurette ? Tout le monde ? Alors il y a une immensité de code commenté qui ne serve à rien(probablement des pétagigaoctets)
J'ai donc répondu non.
Non ce n'est pas différent.Envoyé par hegros
On continue à mettre des commentaires. Que ce soit des cartouches d'entête, des références à la conception ou des indications à un oracle, il faut en mettre.
Bien sûr si tu n'appelles pas « commentaires » ce qui est mis en commentaires pour documenter le code… et que pour toi un commentaire c'est juste une remarque non pertinente et inutile… bin tu as raison. Menfinbon, c'est tiré par les cheveux.
Je ne connais pas un seul sondage non orientéC'est un peu abuser ce sondage.
Ce qu'il veut dire c'est que tu n'expliques pas ton sondage ni ne donne ton propre avis, juste un lien sur n pages discuté depuis n mois.Je ne connais pas un seul sondage non orienté
Et franchement répondre oui ou non à ce genre de question c'est effectivement un mauvais sondage
D'une manière générale, je conseille de commenter le 'pourquoi' plutôt que le 'comment'.
Pour le 'comment' il vaut mieux essayer de rendre son code lisible. En utilisant des noms représentatifs bien sûr mais aussi en encapsulant une portion de code dans des méthodes, en extrayant des classes qui font sens...
Un bon truc à garder en tête: si vous vous sentez obligés de commenter une portion de code, essayer d'extraire ce code dans une méthode dont le nom sera aussi descriptif que l'aurait été le commentaire.
Je vous rassure, il y a toujours des cas où on a besoin de décrire ce que fait le code.
Pour les API, c'est une autre histoire. Là il vaut mieux être assez descriptif avec des exemples.
Bien évidemment oui. Mais
- Comme déjà dit, le "pourquoi" doit primer sur le "comment"
- Et ne jamais oublier que la meilleure des documentations, c'est la qualité et la systématique du nomage des classes / méthodes / variables etc. (et des fichiers qui les contiennent !) .
Par exemple, pas une fois
"int GetMonTruc()" , "void SetMonTruc(int i)"
et une autre
"int MonMachinGet()" , "void MonMachinSet(int i)"
ou pire
"int GetTaChose()" , et son (non-symétrique) "void TaChoseSet(int i)
L'utilité des commentaires
L'utilité des commentaires n'est pas uniquement de documenter le code :
En voilà un débat passionnant, je suis tombé dessus grâce à la newsletter...
Je vais répondre comme il se doit !
J'ai commencé la programmation à 11 ans et j'en ai 36, avec 11 ans de missions dans des grandes boîtes. Mon expérience m'a conduit à écrire un livre, sûrement ressentant le besoin de faire un bilan de toutes ces années de code mais aussi de partager ce que je sais et qui pourrait, sans prétention, être utile à la communauté de mes confrères développeurs. Ce livre s'appelle "Le développement informatique durable". Vous trouverez une critique de Laurent Dardenne sur le site : http://conception.developpez.com/liv...L9782746222465
Ce livre défend de façon militante le développeur, souvent considéré injustement comme « l'ouvrier en bleu de travail de l'informatique », et il délivre ensuite certaines clés liées à la méthode qui doivent lui permettre d'accroitre de façon très significative ses performances.
Parmi ces clés, l'utilisation des commentaires à une place primordiale.
En effet, l'utilisation des commentaires n'a pas pour seul objectif de documenter le code pour nos successeurs ou encore nous même comme on nous le rabâche sans cesse : il doit permettre de donner une forme consciente à la pensée à l'état de fermentation consignées dans notre esprit.
Je m'explique avant qu'on croie que je viens de fumer le St Maclou de Velizy2 :
Pour réaliser ce que l'on pense et évaluer la pertinence de notre raisonnement, il est très utile, voire essentiel, de formaliser cette pensée, et la façon la plus efficace de le faire, hormis la parole est l'écriture.
Ainsi, les commentaires qui précéderont l'écriture de tout code vont "imprimer" notre pensée, et à la lecture de celle-ci, nous allons nous rendre compte des éventuelles lacunes de notre raisonnement pour le repenser, le reformuler et ainsi de suite jusqu'à arriver à une forme juste.
Lorsque ce raisonnement sera arrivé à maturité par l'aller-retour entre les pensées et l'écriture, nous procéderons à la seconde phase qui est l'écriture du code. Vous verrez alors avec quelle fluidité il se déroule puisqu'il n'est plus alors qu'une simple traduction syntaxique. Pour appliquer moi même cette méthode et l'avoir installée dans mon comportement de développeur, j'ai vu mes performances s'accroître d'une façon très significative : code écrit beaucoup plus vite, beaucoup moins de bugs, sérénité…
J'ai nommé cette méthode "l'écriture analytique".
Le chapitre qui lui succède se nomme "l'utilité des commentaires enfin révélée".
On ne peut pas dire que je viens juste faire de la pub pour un bouquin, je pense que ce débat était l'endroit idéal pour en parler.
Pour résumer mon avis, les commentaires sont INDISPENSABLES, d'abord parce qu'ils document le code mais surtout, et c'est là à mon sens la véritable utilité des commentaires, parce qu'ils permettent de structurer et murir notre raisonnement en le façonnant telle une sculpture pour donner ensuite une fluidité incroyable au code et des performances exceptionnelles, où du moins d'un niveau professionnel.
Une vidéo gratuite qui traite du sujet avec démo à l'appui est disponible sur developpez.com : http://delphi.developpez.tv/delphi2008/#session2
Répondre avec citation
Partager