Je distingue documentation et commentaires. La documentation, c'est du texte et des specs.
Bien souvent, quand le code n'est pas clair, c'est qu'il faut revoir les noms des variables, des fonction, l'organisation. C'est facile de cacher la m**** avec 3 lignes de commentaires, qui ne seront pas forcement plus claires que le code. Par experience, je pourrai meme dire moins : quand le code est modifie pour fixer un bug, la documentation ne l'est jamais.
Il y a des cas, oui, ou les choses ne sont pas evidentes : un algorithme metier est l'exemple typique. Mais la plupart du code devrait se lire comme une phrase. Si on respecte les bonnes pratiques, ca pose assez peu de probleme (5 lignes max/fonction, une fonction pour une chose a faire). Le probleme, c'est que 90% du temps, on pond une phrase de commentaire pour remplacer une reflexion sur une factorisation de code, un bon nommage de methodes et de fonctions.
J'aimai bien le code commente. Mais apres avoir applique les recommandations du bouquin, la conclusion est sans appel : le code est plus lisible, plus concis, plus clair, etc.
Concernant les commentaires de code qui mentent, je peux donner une demi douzaine de projets actifs sur github dont les commentaires indiquent le contraire de ce que fait le code, et induisent le lecteur en erreur : au lieu d'aller voir la fonction appelee, il fait confiance au commentaire, qui n'a pas ete mis a jour apres refacto. Sur des projets publics ca arrive, alors sur des projets prives...
Ensuite vient la question du langage/IDE utilise : Java+Eclipse, avec l'aide interractive, ca peut etre utile d'avoir des commentaires 'getAccountList retourne une liste de comptes'. Ca remplace la fraction de seconde de reflection sur la lecture de la fonction. Sur des langages faiblement type, de toute facon il faut lire la documentation et/ou code. le gain de temps est donc ridicule.
Bon, soyons honnetes au final :
* Celui qui va lire le code apprendra (methodes, bonnes pratiques, ...) naturellement. Donc codeur plus efficace.
* Les 5 minutes de lecture du code lui eviteront de se palucher la documentation a chaque appel, de comprendre les choses en prodonfeur. Donc debug plus rapide.
* Avec un peu d'experience sont code sera normalise, plus clair. Donc plus facile a comprendre et debugger pour les autres.
* Le code devrait etre teste. Un test clair qui echoue vaut plus que tout commentaire dans le code. Pour peu que le test soit correctement documente et pas trop tordu (sinon, il faut mettre des commentaires)
Donc au final, je ne suis pas convaincu que commenter systematiquement chaque methode/variable/classe soit bon au final. Ca fait de belles courbes statistiques, mais aucune mesure n'est realis(ee|able) sur la pertinence des commentaires. Pour l'appliquer actuellement, je comprends mieux ce que je fais, je suis plus clair et je comprends plus facilement le code des autres devs. En plus ,je lis du code de personnes techniquement meilleures que moi, du coup je gagne en experience...
[^] # Re: Code auto-documente
Posté par isildur37 . En réponse au sondage Les commentaires et vous ?. Évalué à 5.
Je distingue documentation et commentaires. La documentation, c'est du texte et des specs.
Bien souvent, quand le code n'est pas clair, c'est qu'il faut revoir les noms des variables, des fonction, l'organisation. C'est facile de cacher la m**** avec 3 lignes de commentaires, qui ne seront pas forcement plus claires que le code. Par experience, je pourrai meme dire moins : quand le code est modifie pour fixer un bug, la documentation ne l'est jamais.
Il y a des cas, oui, ou les choses ne sont pas evidentes : un algorithme metier est l'exemple typique. Mais la plupart du code devrait se lire comme une phrase. Si on respecte les bonnes pratiques, ca pose assez peu de probleme (5 lignes max/fonction, une fonction pour une chose a faire). Le probleme, c'est que 90% du temps, on pond une phrase de commentaire pour remplacer une reflexion sur une factorisation de code, un bon nommage de methodes et de fonctions.
J'aimai bien le code commente. Mais apres avoir applique les recommandations du bouquin, la conclusion est sans appel : le code est plus lisible, plus concis, plus clair, etc.
Concernant les commentaires de code qui mentent, je peux donner une demi douzaine de projets actifs sur github dont les commentaires indiquent le contraire de ce que fait le code, et induisent le lecteur en erreur : au lieu d'aller voir la fonction appelee, il fait confiance au commentaire, qui n'a pas ete mis a jour apres refacto. Sur des projets publics ca arrive, alors sur des projets prives...
Ensuite vient la question du langage/IDE utilise : Java+Eclipse, avec l'aide interractive, ca peut etre utile d'avoir des commentaires 'getAccountList retourne une liste de comptes'. Ca remplace la fraction de seconde de reflection sur la lecture de la fonction. Sur des langages faiblement type, de toute facon il faut lire la documentation et/ou code. le gain de temps est donc ridicule.
Bon, soyons honnetes au final :
* Celui qui va lire le code apprendra (methodes, bonnes pratiques, ...) naturellement. Donc codeur plus efficace.
* Les 5 minutes de lecture du code lui eviteront de se palucher la documentation a chaque appel, de comprendre les choses en prodonfeur. Donc debug plus rapide.
* Avec un peu d'experience sont code sera normalise, plus clair. Donc plus facile a comprendre et debugger pour les autres.
* Le code devrait etre teste. Un test clair qui echoue vaut plus que tout commentaire dans le code. Pour peu que le test soit correctement documente et pas trop tordu (sinon, il faut mettre des commentaires)
Donc au final, je ne suis pas convaincu que commenter systematiquement chaque methode/variable/classe soit bon au final. Ca fait de belles courbes statistiques, mais aucune mesure n'est realis(ee|able) sur la pertinence des commentaires. Pour l'appliquer actuellement, je comprends mieux ce que je fais, je suis plus clair et je comprends plus facilement le code des autres devs. En plus ,je lis du code de personnes techniquement meilleures que moi, du coup je gagne en experience...