IdentifiantMot de passe
Loading...
Mot de passe oublié ?Je m'inscris ! (gratuit)
Navigation

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

Débats sur le développement - Le Best Of Discussion :

Programmation : quand faut-il commenter son code ? Google s’invite dans le débat


Sujet :

Débats sur le développement - Le Best Of

  1. #61
    Inactif  

    Homme Profil pro
    Développeur .NET
    Inscrit en
    Janvier 2012
    Messages
    4 904
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 67
    Localisation : Canada

    Informations professionnelles :
    Activité : Développeur .NET
    Secteur : Finance

    Informations forums :
    Inscription : Janvier 2012
    Messages : 4 904
    Points : 10 168
    Points
    10 168
    Billets dans le blog
    36
    Par défaut
    Citation Envoyé par jopopmk Voir le message
    Faisons rapide et simple :

    1. Introduire une variable explicative
    Non, je vais pas rajouter une variable inutile.
    Si vraiment on a besoin d'une explication alors un commentaire va très bien.
    Là j'avoue que cela sort un peu du sujet, mais à la limite, cela peut faire penser à un effet collatéral. Ajouter une (des) variable(s) inutile(s) et faire un traitement sur 2 ou 3 lignes peut faciliter le débogage.

    Ceci dit, je dirais qu'il y a au moins trois occasions où des commentaires sont pratiquement obligatoires, ne serait-ce que par respect pour lecteurs.

    1) Quand on veut déposer le programme-source sur un site où de parfaits débutants pourraient l'utiliser

    2) Quand on est obligé, pour des raisons d'optimisation, ou d'autres raisons techniques, d'utiliser une sorte de "passe croche" inédite ou inconnue. (Ne serait-ce que parce que la mémoire est une faculté qui oublie)

    3) Quand on sait que le programme peut être utilisé très longtemps. (Comme les antiques programmes en COBOL avec des années à juste deux chiffres qui étaient encore là en 1999.)
    À ma connaissance, le seul personnage qui a été diagnostiqué comme étant allergique au mot effort. c'est Gaston Lagaffe.

    Ô Saint Excel, Grand Dieu de l'Inutile.

    Excel n'a jamais été, n'est pas et ne sera jamais un SGBD, c'est pour cela que Excel s'appelle Excel et ne s'appelle pas Access junior.

  2. #62
    Membre éprouvé
    Homme Profil pro
    Intégrateur Web
    Inscrit en
    Août 2012
    Messages
    263
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : Belgique

    Informations professionnelles :
    Activité : Intégrateur Web
    Secteur : High Tech - Multimédia et Internet

    Informations forums :
    Inscription : Août 2012
    Messages : 263
    Points : 1 040
    Points
    1 040
    Par défaut Mais, précisément, comment savoir qui va reprendre le code dans l'avenir ?
    Citation Envoyé par michel.bosseaux Voir le message
    Tout à fait d'accord.
    Les commentaires sont le plus souvent inutiles, sauf quand la personne qui va reprendre le code est un vrai débutant (quand on donne cours par exemple), où là, on n'en met jamais assez ^^
    Mais, précisément, comment savoir qui va reprendre le code dans l'avenir ? Donc, ne faut-il pas toujours commenter ?

  3. #63
    Expert éminent sénior
    Homme Profil pro
    Analyste/ Programmeur
    Inscrit en
    Juillet 2013
    Messages
    4 627
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France, Bouches du Rhône (Provence Alpes Côte d'Azur)

    Informations professionnelles :
    Activité : Analyste/ Programmeur

    Informations forums :
    Inscription : Juillet 2013
    Messages : 4 627
    Points : 10 548
    Points
    10 548
    Par défaut
    Citation Envoyé par martopioche Voir le message
    Mais quel est le rapport avec l'âge du code ? La question est une question sur la pratique actuelle. Foetus, qui est celui que je citais, rebondissait sur "j'écris…", pas "j'écrivais il y a 30 ans…". Parce que le code a 30 ans, les pratiques restent figées à il y a 30 ans ?
    C'est sûr si tu pars du postulat "un commentaire ne sera mis à jour", autant rien commenter
    Et dans ce cas travailler directement sur le code: nom de variables plus explicite, découper les fonctions au risque d'avoir plus d'appels non optimisables, du code plus long parce qu'on rajoute des variables temporaires, ...

    L'idée des 30 ans, c'est du code qui a vécu (maintenu/ mis en production / refactorisé/ ...).
    Et que si dès le départ, le code est commenté et que l'équipe de développement a été rigoureuse sur la mise à jour des commentaires, tu es bien content de les avoir au bout 30 ans.
    Il me semble qu'il y a 30 ans il n'y avait pas de système de gestion de configurations, qui est utile aussi pour un historique.

    Après si tu pars du postulat "Le code n'aura qu'une durée de vie de 2 ans", autant rien commenter

    Et je tiens à préciser une chose: un commentaire ne doit pas être descriptif, sauf cas très particulier
    C'est pour cela que je l'utilise pour décrire les formules mathématiques (par exemple), pour garder du code mort, pour marquer du code, pour alerter d'une chose (XXX), ...
    Et comme il n'est pas descriptif, s'il n'est pas mis à jour, c'est moins grave (sauf éventuellement quelques alertes).

    Citation Envoyé par martopioche Voir le message
    Et truc qui marche sans broncher…*Si par ce process, il livre avec du code de dev ou qu'après la livraison les devs ont du code de prod, on est bien d'accord que ce truc "ne marche pas", non ?
    Mais dans la vraie vie, des fois, on n'a pas les outils pour

    Par exemple, je vois que dans le développement Web, lorsqu'on commit du code, il est analysé (JSLint), il est testé, voir plus, ...

    En C++, des fois tu n'as qu'un compilateur. Moi, je travaillais sans système de gestion de configurations, et les quelques tests étaient manuels.
    Donc, oui c'est dangereux de retirer/ remettre du code à la main (essentiellement pour tester/ déboguer), mais des fois tu es obligé.
    D'où l'utilisation des commentaires pour faciliter les manœuvres.

    Il y aurait une autre solution: la conception. Par exemple, intégrer un système de log (fichiers et réseau) et qu'on puisse l'activer à la ligne de commande.
    Le problème, c'est que cela demande du temps

    Citation Envoyé par sirthie Voir le message
    Mais, précisément, comment savoir qui va reprendre le code dans l'avenir ? Donc, ne faut-il pas toujours commenter ?
    Et encore plus (<- Dupont ) on peut extraire une partie du code pour un autre projet.

  4. #64
    Membre confirmé
    Profil pro
    Inscrit en
    Novembre 2003
    Messages
    114
    Détails du profil
    Informations personnelles :
    Localisation : France

    Informations forums :
    Inscription : Novembre 2003
    Messages : 114
    Points : 618
    Points
    618
    Par défaut google grillé dans son exemple ...
    Quels beaux exemples, prenons le premier avec la variable explicative :

    Code : Sélectionner tout - Visualiser dans une fenêtre à part
    1
    2
    3
    4
    price = numItems * itemPrice;
    discount =
        min(5, numItems) * itemPrice * 0.1;
    finalPrice = price - discount;
    Pourquoi est-ce le minimum entre 5 et le nombre d'items ?
    Un petit commentaire explicatif ?

    genre
    //réduction totale = -10% prix unitaire, sur 5 articles au maximum

    Et la valeur de discount unitaire en dur, très propre

  5. #65
    Membre éclairé
    Profil pro
    Inscrit en
    Décembre 2006
    Messages
    614
    Détails du profil
    Informations personnelles :
    Localisation : France

    Informations forums :
    Inscription : Décembre 2006
    Messages : 614
    Points : 713
    Points
    713
    Par défaut
    Citation Envoyé par sirthie Voir le message
    Mais, précisément, comment savoir qui va reprendre le code dans l'avenir ? Donc, ne faut-il pas toujours commenter ?
    Si la question est par rapport à ta citation, la question est simple : c'est quoi le but de ton job ? Si c'est faire de l'enseignement, oui. Si c'est produire du code et le maintenir, on va supposer qu'il sera repris par un développeur. Si celui qui reprends ce code n'a pas "la compétence", ce n'est pas à toi de compenser l'incompétence du management qui ne sait pas staffer ses équipes.

    Citation Envoyé par foetus Voir le message
    C'est sûr si tu pars du postulat "un commentaire ne sera mis à jour", autant rien commenter
    Allez, on va être pragmatiques : peux-tu citer où j'ai fait ce postulat ?

    Après si tu pars du postulat "Le code n'aura qu'une durée de vie de 2 ans", autant rien commenter
    Là aussi : peut-tu citer où j'ai fait ce postulat ?

    Mais dans la vraie vie, des fois, on n'a pas les outils pour
    La vrai vie ? Ah, un commentaire qui indique que la suite de l'intervention sera su sophisme

    Citation Envoyé par gagaches Voir le message
    Quels beaux exemples, prenons le premier avec la variable explicative :

    Code : Sélectionner tout - Visualiser dans une fenêtre à part
    1
    2
    3
    4
    price = numItems * itemPrice;
    discount =
        min(5, numItems) * itemPrice * 0.1;
    finalPrice = price - discount;
    Pourquoi est-ce le minimum entre 5 et le nombre d'items ?
    Un petit commentaire explicatif ?
    Les commentaires n'ont pas pour but de recopier le cahier des charges ou la documentation fonctionnelle.

  6. #66
    Membre confirmé
    Profil pro
    Inscrit en
    Novembre 2003
    Messages
    114
    Détails du profil
    Informations personnelles :
    Localisation : France

    Informations forums :
    Inscription : Novembre 2003
    Messages : 114
    Points : 618
    Points
    618
    Par défaut
    Citation Envoyé par martopioche Voir le message
    Si la question est par rapport à ta citation, la question est simple : c'est quoi le but de ton job ? Si c'est faire de l'enseignement, oui. Si c'est produire du code et le maintenir, on va supposer qu'il sera repris par un développeur. Si celui qui reprends ce code n'a pas "la compétence", ce n'est pas à toi de compenser l'incompétence du management qui ne sait pas staffer ses équipes.
    [...]
    Les commentaires n'ont pas pour but de recopier le cahier des charges ou la documentation fonctionnelle.
    Les commentaires ont pour but de rendre le code compréhensible.

    Tu préfères quoi ?
    un code comme le premier exemple et "charge à toi" d'aller trouver dans la documentation le pourquoi du code ?
    ou un code explicité avec un commentaire qui indique l'élément de difficulté, comme ici le "min(5,numitem)" pour la réduction ?

    Ne crois-tu pas que ça permet de gagner BEAUCOUP de temps dans la lecture et sa compréhension ?

    J'ai fais du dev avec gestion des requirements & TMA associée.

    Donc chaque requirement était tracé dans les commentaires du code pour prouver que le requirement avait été réalisé par le bout de code identifié.
    Et cela pour gérer le suivi des fonctionnalités et gérer la configuration logicielle
    Par exemple, chaque anomalie/évolution était bornée de commentaires du genre :
    /** début ano00001 **/
    ....
    /** fin ano00001 **/

    Maintenant, et c'est un avis personnel, je préfère plus de commentaire que moins de commentaires.
    Je préfère une personne qui aura écrit tout son code en algorithme dans les commentaires avec le code associé en dessous,
    qu'une personne qui fera tout sans AUCUNE ligne de code.

    Bref, mieux vaut trop d'information que pas assez.
    Parce que typiquement, oser croire que la documentation est toujours retrouvable et bien à jour, c'est naif

  7. #67
    Membre expérimenté
    Profil pro
    chercheur
    Inscrit en
    Avril 2004
    Messages
    830
    Détails du profil
    Informations personnelles :
    Localisation : France, Essonne (Île de France)

    Informations professionnelles :
    Activité : chercheur

    Informations forums :
    Inscription : Avril 2004
    Messages : 830
    Points : 1 453
    Points
    1 453
    Par défaut
    Citation Envoyé par martopioche Voir le message
    Les commentaires n'ont pas pour but de recopier le cahier des charges ou la documentation fonctionnelle.
    Je pense que si. Et que de façon générale les commentaires doivent être écrits avant le code. Si on définit précisément ce qu'il faut faire, coder ou recoder est beaucoup plus facile
    Ce qui s'énonce clairement se conçoit bien ( Le hautbois)

  8. #68
    Expert éminent
    Avatar de transgohan
    Homme Profil pro
    Développeur Temps réel Embarqué
    Inscrit en
    Janvier 2011
    Messages
    3 146
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France, Maine et Loire (Pays de la Loire)

    Informations professionnelles :
    Activité : Développeur Temps réel Embarqué

    Informations forums :
    Inscription : Janvier 2011
    Messages : 3 146
    Points : 9 386
    Points
    9 386
    Par défaut
    Citation Envoyé par Nebulix Voir le message
    Les commentaires n'ont pas pour but de recopier le cahier des charges ou la documentation fonctionnelle.
    Je pense que si. Et que de façon générale les commentaires doivent être écrits avant le code. Si on définit précisément ce qu'il faut faire, coder ou recoder est beaucoup plus facile
    Je dirai tout l'inverse.
    Une constante doit être le reflet de la spécification.
    Un commentaire doit parler de cette constante sans parler de sa valeur.

    Car la constante quand elle est utilisée dans 30 fichiers et qu'elle a 30-40 commentaires associés c'est casse-gueule de tout mettre à jour lorsque la spécification change...

    « Toujours se souvenir que la majorité des ennuis viennent de l'espace occupé entre la chaise et l'écran de l'ordinateur. »
    « Le watchdog aboie, les tests passent »

  9. #69
    Membre éclairé
    Profil pro
    Inscrit en
    Décembre 2006
    Messages
    614
    Détails du profil
    Informations personnelles :
    Localisation : France

    Informations forums :
    Inscription : Décembre 2006
    Messages : 614
    Points : 713
    Points
    713
    Par défaut
    Citation Envoyé par gagaches Voir le message
    Les commentaires ont pour but de rendre le code compréhensible.
    Oui, le code, pas le métier.

    Tu préfères quoi ?
    un code comme le premier exemple et "charge à toi" d'aller trouver dans la documentation le pourquoi du code ?
    ou un code explicité avec un commentaire qui indique l'élément de difficulté, comme ici le "min(5,numitem)" pour la réduction ?

    Ne crois-tu pas que ça permet de gagner BEAUCOUP de temps dans la lecture et sa compréhension ?
    Il n'y a pas d'élément de difficulté ici, il y a une connaissance métier (en considérant que le code de prod' n'a pas de données magiques comme peut l'avoir un code d'illustration que tu cite ici). Le métier est défini dans les spec fonctionnelles et ce document a été (en théorie) lu, relu, validé et a une valeur contractuelle entre ce qui est demandé et ce qui est fourni. Un commentaire, c'est un texte qu'a ajouté un développeur, qui a été transformé, adapté et dont je n'ai aucune connaissance de la fiabilité et maintenance, à moins que toi tu l'ai…

    Même en considérant que le commentaire est fiable, me dire que tu a gagné du temps à savoir quoi faire signifie que tu a certainement gagné du temps à introduire d'autres régressions : si tu n'a aucune connaissance du métier et que tu ne te repose que sur les commentaires locaux, comment sait-tu que tu n'a pas engendré d'autres effets de bord du fait de renseignements dans des commentaires qui ne concernent pas ton intervention ?

    J'ai fais du dev avec gestion des requirements & TMA associée.

    Donc chaque requirement était tracé dans les commentaires du code pour prouver que le requirement avait été réalisé par le bout de code identifié.
    Et cela pour gérer le suivi des fonctionnalités et gérer la configuration logicielle
    Par exemple, chaque anomalie/évolution était bornée de commentaires du genre :
    /** début ano00001 **/
    ....
    /** fin ano00001 **/
    Et question : quand un dev reprend ce code pour une évolution, ces commentaires, ça lui apporte quelque chose ?

    Sérieux, vous faites de l'archéologie ou de l'info ? "Preuve" ? Mais de quoi ? Un commentaire ne montre absolument pas une réalisation, la réalisation est démontrée par les TU à la rigueur. Quand aux suivis, les SCMs servent à ça aujourd'hui…

    Bref, mieux vaut trop d'information que pas assez.
    Illusion habituelle qui oublie que "trop d'information" est le plus souvent ignorée et similaire à pas d'information…

    Parce que typiquement, oser croire que la documentation est toujours retrouvable et bien à jour, c'est naif
    Oh…*Intéressant, et donc on peut supposer que le commentaire est bien à jour par rapport à la spécification…

    Citation Envoyé par Nebulix Voir le message
    Je pense que si. Et que de façon générale les commentaires doivent être écrits avant le code. Si on définit précisément ce qu'il faut faire, coder ou recoder est beaucoup plus facile
    Si tu parle de mettre des commentaires sur une page blanche en guise d'algo, pourquoi pas. Mais les laisser par la suite, quel apport au lecteur ?

  10. #70
    Expert éminent
    Avatar de Pyramidev
    Homme Profil pro
    Développeur
    Inscrit en
    Avril 2016
    Messages
    1 460
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France, Haute Garonne (Midi Pyrénées)

    Informations professionnelles :
    Activité : Développeur

    Informations forums :
    Inscription : Avril 2016
    Messages : 1 460
    Points : 6 064
    Points
    6 064
    Par défaut
    Citation Envoyé par gagaches Voir le message
    Par exemple, chaque anomalie/évolution était bornée de commentaires du genre :
    /** début ano00001 **/
    ....
    /** fin ano00001 **/
    C'est une convention qui date d'une ancienne époque. Maintenant, pour ce genre de chose, on utilise un logiciel de gestion de versions (en anglais, Version Control System ou VCS), comme SVN, Git et Mercurial.

    Concrètement, quand tu as fini d'implémenter un ticket (évolution ou anomalie), tu fais un commit avec un petit commentaire, par exemple "ano00001" suivi d'une description brève.
    Ensuite, quand tu as besoin de voir l'évolution d'un fichier, via le logiciel de gestion de versions, tu peux voir la liste des commits rangés par ordre chronologique qui concernent ce fichier.
    Pour chaque commit, tu peux voir la date, le petit commentaire et la liste des fichiers que ce commit a modifiés.
    Pour chacun de ces fichiers, tu peux aussi voir la liste des différences avant et après le commit.

    Rq : martopioche parle de SCM (Source Code Manager). Je crois que le sens est similaire à celui de VCS.

  11. #71
    Membre éclairé
    Profil pro
    Inscrit en
    Décembre 2006
    Messages
    614
    Détails du profil
    Informations personnelles :
    Localisation : France

    Informations forums :
    Inscription : Décembre 2006
    Messages : 614
    Points : 713
    Points
    713
    Par défaut
    Citation Envoyé par Pyramidev Voir le message
    Rq : martopioche parle de SCM (Source Code Manager). Je crois que le sens est similaire à celui de VCS.
    Yep, j'ai arrêté de pinailler sur les termes vu que l'on trouve SCM ou VCS pour les même outils et que de la même manière là où à une époque on avait des outils pour une gestion, ils ont évolués (je pense à Clearcase qui est un gestionnaire de configurations mais qui est vendu comme un gestionnaire de versions de code source…).

  12. #72
    Membre confirmé
    Profil pro
    Inscrit en
    Novembre 2003
    Messages
    114
    Détails du profil
    Informations personnelles :
    Localisation : France

    Informations forums :
    Inscription : Novembre 2003
    Messages : 114
    Points : 618
    Points
    618
    Par défaut
    Citation Envoyé par martopioche Voir le message
    Oui, le code, pas le métier.
    sachant que le code est la traduction des besoins métiers, et donc de leurs spécificités ...
    c'est le serpent qui se mort la queue.

    Citation Envoyé par martopioche Voir le message
    Il n'y a pas d'élément de difficulté ici, il y a une connaissance métier (en considérant que le code de prod' n'a pas de données magiques comme peut l'avoir un code d'illustration que tu cite ici). Le métier est défini dans les spec fonctionnelles et ce document a été (en théorie) lu, relu, validé et a une valeur contractuelle entre ce qui est demandé et ce qui est fourni. Un commentaire, c'est un texte qu'a ajouté un développeur, qui a été transformé, adapté et dont je n'ai aucune connaissance de la fiabilité et maintenance, à moins que toi tu l'ai…

    Même en considérant que le commentaire est fiable, me dire que tu a gagné du temps à savoir quoi faire signifie que tu a certainement gagné du temps à introduire d'autres régressions : si tu n'a aucune connaissance du métier et que tu ne te repose que sur les commentaires locaux, comment sait-tu que tu n'a pas engendré d'autres effets de bord du fait de renseignements dans des commentaires qui ne concernent pas ton intervention ?
    Il y a bien un élément de difficulté quand on fait un calcul partiel.
    Et oui, le commentaire est fiable dans ce cas. Et bien sûr que j'ai gagné du temps.
    Le dev a indiqué ce qu'il voulait faire ...
    un coup d'oeil à la spec ensuite pour vérifier que l'implémentation est bonne et fin.

    Ensuite, je veux bien voir la gueule de ton code, de tes versions et de tes git avec la mode actuelle du CI qui amène à faire 10x commits / jour sur la même anomalie/même bug, afin que les tests passent dessus.
    Car oui, prétendre qu'une correction d'anomalie est unitaire à un seul commit, c'est faux.
    Sans parler des commit dégueulasses en mode "commit." sans détail, mais c'est un autre sujet.

    On va avoir potentiellement plusieurs commits successifs avec des évolutions partielles, rien que pour la recette unitaire et les tests et on va partir en archéologie dans les X dernières versions commitées pour comprendre de quoi ça retourne.

    Après, oui, les systèmes de gestion de code source ou de gestion de configuration (git, svn, clearcase) et les outils de tracking d'issue associés (jira, redmine, clearquest, ...) permettent un suivi des ano/évol.
    Par exemple, à l'époque de Clearcase/clearquest, on pouvait lors de l'équivalent du commit forcer l'association par un champ dans une liste déroulante à une issue créée dans clearquest qui portait et réalisait le diff global du code associée.
    Donc code modifié forcément associé à une issue (ano, évol, ...) et avec un risque d'erreur "minime".

    De nos jours, la liaison reste plus laxe et il faut rajouter des *commentaires* () dans le commit avec une référence à une issue des bugtrackers (jira, redmine, ...) pour faire le suivi des diffs.
    une coquille dans le commentaire et la liaison ne se fera plus.

    Bref, je maintiens et persiste.
    Oser prétendre que le commentaire associé au code serait moins proche de la réalité du code que les spec fonctionnelles ...
    Oser dire qu'il faut moins de commentaire plutôt que plus de commentaire ...

    C'est se voiler la face dans un idéalisme qui n'existe pas.

  13. #73
    Rédacteur
    Avatar de Franck.H
    Homme Profil pro
    Développeur .NET
    Inscrit en
    Janvier 2004
    Messages
    6 951
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 46
    Localisation : France, Haut Rhin (Alsace)

    Informations professionnelles :
    Activité : Développeur .NET
    Secteur : Service public

    Informations forums :
    Inscription : Janvier 2004
    Messages : 6 951
    Points : 12 462
    Points
    12 462
    Par défaut
    J'applique les mêmes méthodes que Google dans ce cas, je nomme mes foncions/méthodes/variables/classes et autres objets selon leur utilité et avec les détails qui s'impose.
    Je ne documente que des parties critiques et plus complexe mais c'est dans ce cas de plus gros blocs de code, surtout lorsqu'il y a plusieurs conditions et donc plusieurs mode de fonctionnement.
    Mon Site
    Ma bibliothèque de gestion des chaînes de caractères en C

    L'imagination est plus importante que le savoir. A. Einstein

    Je ne répond à aucune question technique par MP, merci d'avance !

  14. #74
    Expert éminent
    Avatar de transgohan
    Homme Profil pro
    Développeur Temps réel Embarqué
    Inscrit en
    Janvier 2011
    Messages
    3 146
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France, Maine et Loire (Pays de la Loire)

    Informations professionnelles :
    Activité : Développeur Temps réel Embarqué

    Informations forums :
    Inscription : Janvier 2011
    Messages : 3 146
    Points : 9 386
    Points
    9 386
    Par défaut
    Ensuite, je veux bien voir la gueule de ton code, de tes versions et de tes git avec la mode actuelle du CI qui amène à faire 10x commits / jour sur la même anomalie/même bug, afin que les tests passent dessus.
    Car oui, prétendre qu'une correction d'anomalie est unitaire à un seul commit, c'est faux.
    Sans parler des commit dégueulasses en mode "commit." sans détail, mais c'est un autre sujet.
    Bah... Tu as x commits en branche de développement mais un seul commit en branche de livraison (le merge de ta branche de développement)...
    Donc quand on regarde en branche de livraison c'est limpide comme de l'eau de roche...

    Après c'est sûr que si les tests ne se passent que sur la branche de livraison...

    « Toujours se souvenir que la majorité des ennuis viennent de l'espace occupé entre la chaise et l'écran de l'ordinateur. »
    « Le watchdog aboie, les tests passent »

  15. #75
    Membre averti

    Profil pro
    Inscrit en
    Juin 2005
    Messages
    351
    Détails du profil
    Informations personnelles :
    Localisation : Suisse

    Informations forums :
    Inscription : Juin 2005
    Messages : 351
    Points : 446
    Points
    446
    Par défaut
    Personnellement, je sais que je commente beaucoup, voire un peu trop, mais c'est aussi parce que j'explique d'abord les fonctionnalités de la méthode, ses comportements vis-à-vis des paramètres spéciaux (comment ma fonction répond-elle si le nombre est zéro, négatif, etc.) et après je déroule les étapes logiques sous la forme de commentaire dans le corps de la fonction. Ce n'est qu'après que je vais réellement coder tout cela et tant pis si mon bloc "éliminer les valeurs absurdes" est implémenté par 10 lignes de code ou un stupide appel "RemoveOutOfRangeValues()". Comme ça je peux refactoriser des sections de codes tout en m'assurant que je garde les bonnes fonctionnalités.

    Ensuite, je ne crois pas qu'on puisse "trop commenter": d'abord ce qui est évident pour moi ne l'est pas forcément pour les autres qui reprendront mon code. Ensuite, il n'y a rien de pire que ces documentations qui n'expliquent pas comment se comporte une fonction. Que se passe-t-il si la fonction "CalculerAgeCapitaine" trouve -1, 0, 1000 ou s'il est mineur ? Dois-je traiter moi-même la valeur retournée, traiter des exceptions (au sens "catch()"), etc. Et la réalité, c'est qu'un manque d'information est pénalisant contrairement un à un code qui est un peu trop commenté (au pire on lit deux fois la même choses sous deux formes différentes et si on ne comprend pas l'une on comprendra l'autre)...

  16. #76
    Membre habitué
    Inscrit en
    Octobre 2004
    Messages
    83
    Détails du profil
    Informations forums :
    Inscription : Octobre 2004
    Messages : 83
    Points : 132
    Points
    132
    Par défaut software craftsmanship
    L'occasion de refaire un peu de pub pour cet excellent bouquin Robert C. Martin : "Coder proprement" ...."un commentaire utile est celui qu'on n'a pas besoin d'écrire"

    Le commentaire est souvent une excuse ou une facilité pour laisser du code crade.
    Je préfère pas de commentaire à un mauvais commentaire qui va induire en erreur.

    Ainsi source autodescriptif = le développeur veille à nommer précisément ses intentions, ce qu'il fait, le "comment" et le "quoi"
    Le commentaire sera complémentaire pour indiquer le "pourquoi" (choix d'une implémentation plûtot qu'une autre, etc.)
    Doc utilisateur (javadoc...) : uniquement pour des API externes/publiques, si boite noire ça peut être utile pour l'équipe de développement mais en général ce sont des spécialistes de ces boites noires donc à quoi bon polluer le code et maintenir une javadoc...
    Les tests précis et bien nommés peuvent aussi faire office de documentation, exemples, tutos, notamment pour tout ce qui est "code privé" justement...c'est d'ailleurs ce qui est souvent le plus facilement/nécessairement testable (test unitaire).

  17. #77
    Membre averti
    Profil pro
    Inscrit en
    Septembre 2009
    Messages
    156
    Détails du profil
    Informations personnelles :
    Localisation : France

    Informations forums :
    Inscription : Septembre 2009
    Messages : 156
    Points : 306
    Points
    306
    Par défaut
    En fait, dans les exemples cités et dans vos remarques, je m'aperçois qu'on n'a absolument pas la même manière de coder.
    Je ne marque pas dans mes commentaires les conneries des exemples.
    Par contre, j'explique la logique ou l'algorithme que je vais utiliser dans la fonction, pour éviter que celui qui va maintenir se paluche tout le code pour le déduire. Cela est bien plus utile que ce que je vois ailleurs dans vos exemples.

  18. #78
    Membre à l'essai
    Homme Profil pro
    Étudiant
    Inscrit en
    Août 2015
    Messages
    31
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 31
    Localisation : Congo-Brazzaville

    Informations professionnelles :
    Activité : Étudiant

    Informations forums :
    Inscription : Août 2015
    Messages : 31
    Points : 19
    Points
    19
    Par défaut
    tout à fait d'accord,le fait de donner des noms significatifs à ses variables et fonctions permet une bonne lisibilité du code et évite les commentaires.

  19. #79
    Membre habitué
    Inscrit en
    Octobre 2004
    Messages
    83
    Détails du profil
    Informations forums :
    Inscription : Octobre 2004
    Messages : 83
    Points : 132
    Points
    132
    Par défaut
    Citation Envoyé par singman Voir le message
    En fait, dans les exemples cités et dans vos remarques, je m'aperçois qu'on n'a absolument pas la même manière de coder.
    Je ne marque pas dans mes commentaires les conneries des exemples.
    Par contre, j'explique la logique ou l'algorithme que je vais utiliser dans la fonction, pour éviter que celui qui va maintenir se paluche tout le code pour le déduire. Cela est bien plus utile que ce que je vois ailleurs dans vos exemples.
    Ecrire un commentaire qui décrit ce que le code fait ça revient :
    - à faire 2 fois le boulot
    - à doubler les efforts de maintenance : avec un gros risque de désynchro .....et si le commentaire dit que le code fait autre chose que ce qu'il fait vraiment, c'est double peine !
    - à se faciliter la vie : code incompréhensible nécessitant un fort degré d'analyse et de déduction, plutôt que de le rendre plus compréhensible je rédige un petit commentaire vite fait pour me dédouaner ("un bon commentaire est celui qu'on peut éviter d'écrire")

    Si faut se "palucher tout le code pour déduire ce qu'il fait" c'est que sa structuration peut être améliorée.
    Plusieurs pistes :
    - meilleur nommage des variables, fonctions, etc
    - découpage d'un code complexe en codes unitaires plus compréhensibles
    - ordre du code dans un fichier source (une classe en prog objet par exemple) : comme pour un article de journal, commencer par les fonctions (unitaires) les plus "conceptuelles"/générales puis descendre vers de plus en plus de détails (implémentations)...au même titre qu'un lecteur de journal lira d'abord un titre puis une accroche ("chapeau" en jargon journalistique si je ne m'abuse) puis les détails de l'article, un développeur lira d'abord un package, puis un nom de classe, puis les API proposées par la classe et au bout du bout s'il s'agit bien de ce qu'il ciblait, le détail des implémentations.

    Je n'invente rien, tout est tiré du livre de Robert C Martin "Coder proprement"....une référence pour beaucoup dans ce domaine, perso avant de le lire en pensant coder "propre" je faisais réellement tout l'inverse, je ne me jette pas la pierre juste que je n'avais jamais réellement été formé en la matière et ce livre permet de bénéficier de l'expérience de toute une vie de développeurs connus/réputés...un recul impossible à prendre suffisamment tôt dans une carrière sinon !

  20. #80
    Membre habitué
    Inscrit en
    Octobre 2004
    Messages
    83
    Détails du profil
    Informations forums :
    Inscription : Octobre 2004
    Messages : 83
    Points : 132
    Points
    132
    Par défaut
    Citation Envoyé par Makelzauvic Voir le message
    tout à fait d'accord,le fait de donner des noms significatifs à ses variables et fonctions permet une bonne lisibilité du code et évite les commentaires.
    +1

    Un exemple tout bête : préciser l'unité de mesure dans une variable métrique (temps, distance, etc...).
    Si j'ai une API qui me met demande un paramètre "time" (passons sur le fait que "time" reste hyper générique et pourrait être plus précis quand à la signification de la variable) et que je dois lire la doc pour savoir que c'est en secondes, pourquoi ne pas directement indiquer "timeInSeconds" !

Discussions similaires

  1. Réponses: 25
    Dernier message: 06/01/2013, 18h22
  2. Faut-il commenter son code source pour le rendre plus lisible et maintenable ?
    Par mayayu dans le forum Débats sur le développement - Le Best Of
    Réponses: 149
    Dernier message: 09/11/2009, 03h30
  3. Bien commenter son code Java
    Par shaun_the_sheep dans le forum Général Java
    Réponses: 2
    Dernier message: 27/05/2008, 12h13
  4. Comment commenter son code source proprement ...
    Par basnifo dans le forum MFC
    Réponses: 3
    Dernier message: 31/03/2006, 17h22

Partager

Partager
  • Envoyer la discussion sur Viadeo
  • Envoyer la discussion sur Twitter
  • Envoyer la discussion sur Google
  • Envoyer la discussion sur Facebook
  • Envoyer la discussion sur Digg
  • Envoyer la discussion sur Delicious
  • Envoyer la discussion sur MySpace
  • Envoyer la discussion sur Yahoo