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 :

Un code bien écrit a-t-il besoin des commentaires ?


Sujet :

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

  1. #101
    r0d
    r0d est déconnecté
    Expert éminent

    Homme Profil pro
    Développeur de jeux vidéo
    Inscrit en
    août 2004
    Messages
    4 261
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France, Ain (Rhône Alpes)

    Informations professionnelles :
    Activité : Développeur de jeux vidéo

    Informations forums :
    Inscription : août 2004
    Messages : 4 261
    Points : 6 603
    Points
    6 603
    Billets dans le blog
    2
    Par défaut
    Une autre exemple de commentaire utile:
    Nous avons une fonction DoSomething() et après profiling, on se rend compte que cette fonction est appelée beaucoup de fois et qu'un peu d'optimisation sur cette fonction pourrait nous faire gagner de précieuses secondes au runtime. On décide donc d'optimiser à l'extrême cette fonction DoSomething(), on insère une morceau d'assembleur (après s'être assuré qu'on fait mieux que le compilo), on transforme l'algo en une heuristique qui nous fait gagner du temps dans 95% des cas, etc, et au final, le code résultant en devient incompréhensible. Dans ce cas, il est bon de laisser l'ancien code en commentaire, et si possible, d'expliquer un peu le pourquoi des modifications.
    Tester c'est douter, corriger c'est abdiquer.

  2. #102
    Membre émérite

    Profil pro
    Inscrit en
    décembre 2003
    Messages
    3 995
    Détails du profil
    Informations personnelles :
    Localisation : France

    Informations forums :
    Inscription : décembre 2003
    Messages : 3 995
    Points : 2 388
    Points
    2 388
    Par défaut
    D'une manière générale, il y a forcément une complexité dans tout code. Après tout, on cherche généralement à faire quelque chose d'assez compliqué, et on doit bien retrouver cette complexité quelque part.

    Découper son code en petites opérations est sans doute une bonne chose, quand c'est faisable. Mais il vient toujours un moment où on doit gérer les différents cas de figure que doit traiter l'application et où même le simple "aiguillage" entre les cas peut déjà faire un bon paquet de code. De plus, les indirections sont elles-même une forme de complexité (qui ne s'est jamais retrouvé en train d'essayer de remonter le fil d'une méthode qui appelle une autre méthode qui appelle une autre méthode...). Les commentaires aux endroits difficiles sera donc toujours nécessaire à mon avis. Toutefois, se poser la question de réécrire une portion de code qui a besoin de commentaires est sans doute une bonne idée, même si on peut parfaitement décider au final de laisser en l'état.

    Ensuite, il y a un truc qui m'agace (et qu'on retrouve jusque dans les javadocs Spring ou Apache Commons) : les commentaires évidents, dans le genre :

    Code : Sélectionner tout - Visualiser dans une fenêtre à part
    1
    2
    3
    4
    5
    6
    7
    /**
    * Fait des trucs
    * @param bidule Le bidule pour faire des trucs
    */
    public void faitDesTrucs(int bidule) {
      //Fait des trucs
    }
    Ce type de commentaire est une pure perte de temps et d'espace. Ça rallonge le code sans rien apporter.

  3. #103
    Membre éclairé
    Homme Profil pro
    Développeur informatique
    Inscrit en
    janvier 2010
    Messages
    434
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 35
    Localisation : France, Loire Atlantique (Pays de la Loire)

    Informations professionnelles :
    Activité : Développeur informatique

    Informations forums :
    Inscription : janvier 2010
    Messages : 434
    Points : 654
    Points
    654
    Par défaut
    Bonjour,

    Le problème c'est le temps, si le code et propre aujourd'hui le sera t'il demain.
    Les commentaires permettent de garder la connaissance.

    Dans les trucs agaçant c'est le code mort, les commentaires sur l'humeur de la personne le jour il a fait le commentaire et le gros todo vieux de 10 ans penser a remplir ce bloque.

  4. #104
    Membre éprouvé
    Profil pro
    Inscrit en
    juin 2008
    Messages
    598
    Détails du profil
    Informations personnelles :
    Localisation : Belgique

    Informations forums :
    Inscription : juin 2008
    Messages : 598
    Points : 1 034
    Points
    1 034
    Par défaut
    Salut
    -----

    Code : Sélectionner tout - Visualiser dans une fenêtre à part
    1
    2
    3
    4
    5
    6
    7
    // <summary>
            /// Calcul du taux de TVA
            /// </summary>
            /// <param name="pValeurHt">valeur Hors taxe</param>
            /// <param name="pTaux">taux de tva</param>
            /// <returns>valeur Hors taxe * le taux de tva</returns>
            public decimal CalculTVA(decimal pValeurHt,decimal pTaux)
    Pour moi ici le commentaire n'apporte rien de plus si ça n'est de la pollution visuel, je préfère :
    À mon avis, puisqu'on parle de commentaires, il faudrait déjà savoir si tout le monde parle de la même chose. Parce que ci-dessus ce n'est pas du commentaire de code, c'est de la génération de documentation. Remettre en question la documentation, c'est aller encore plus loin que remettre en question les commentaires.

    Sur le point que trop de commentaires peuvent être dérangeants, c'est peut-être parce que ceux qui commentent manquent d'imagination pour organiser leurs commentaires.

    Ainsi, pour reprendre ce cas cité contenant évidemment des commentaires inutiles (c'est juste pour l'exemple) et dérangeant la relecture:

    Code : Sélectionner tout - Visualiser dans une fenêtre à part
    1
    2
    3
    4
    5
    6
    7
    8
    9
           private decimal CalculTVA(decimal pValeurHt,decimal pTaux)
            {
                // Initilisation des variables
                decimal lValeurCalculer;
                // calcule du taux
                lValeurCalculer = pValeurHt * pTaux;
                //on retourne la valeur
                return lValeurCalculer;
            }
    Il suffit de vraiment pas grand chose pour transformer ces commentaires inutiles dérangeants en commentaires (toujours inutiles dans ce cas simpliste) plus du tout dérangeant à la lecture :
    Code : Sélectionner tout - Visualiser dans une fenêtre à part
    1
    2
    3
    4
    5
    6
    7
     
           private decimal CalculTVA(decimal pValeurHt,decimal pTaux)
            {
                decimal lValeurCalculer;                     // initialisations
                lValeurCalculer = pValeurHt * pTaux;         // valeur TVA
                return lValeurCalculer;                      // retour TVA
            }
    Je veux les commentaires, je lis à droite, je veux le code, je lis à gauche.

    Pour l'argument concernant le fait qu'un code bien écrit est lisible sans commentaires, j'ai du aller relire la page d'accueil du forum pour voir si le sujet était "absence de commentaires dans C#" ou "absence de commentaires dans les codes".

    Parce que je peux fournir des routines très courtes et très bien écrites en langage d'assemblage de microcontrôleurs, absolument incompréhensibles sans les commentaires correspondants. Il s'agit pourtant de fonctions mathématiques basiques.

    Pour le découpage du code, moi je suis pour scinder le code dans le sens de factorisation. C'est à dire que je scinde si les parties factorisées on un intérêt à être ré-utilisées plusieurs fois à partir de plusieurs endroits différents. Si le but est de couper une méthode de 100 lignes en 10 méthodes de 10 lignes sans objectif de réutilisation, je trouve ça nuisible, pour les raisons suivantes :

    - Ce n'est pas plus simple à lire, surtout si au fil du temps les morceaux de routines se retrouvent dispersées dans le reste du programme. Je préfère avoir toute la routine sous les yeux que de jouer de la molette de souris pour trouver tous les fragments de routines. Dans un langage objet, par exemple, le jeu de piste des héritages est déjà suffisamment complexe pour ajouter en plus des méthodes coupées en petits bouts non fonctionnels individuellement.

    - Le risque est bien réel qu'une méthode écrite dans l'unique but de raccourcir le nombre de lignes soit réutilisée en tant que méthode opérationnelle réutilisable, et donc ne se retrouve appelée dans le futur à partir d'endroits où ce n'était pas prévu. Le risque étant alors que cette routine ayant été écrite dans un contexte particulier, et donc sans toutes les vérifications nécessaires, se retrouve appelée dans un contexte qui ne lui permet pas de fonctionner correctement

    - Et, inversement, si on veut éviter ce problème, on doit ajouter à la méthode tous les tests nécessaires (variables nulles, limites d'utilisation etc) pour qu'elle puisse fonctionner dans tous les contextes. Au final, on risque bien de se retrouver à remplacer une méthode de 100 lignes par 10 méthodes de 50 lignes, c'est tout sauf efficace, simple à lire, et utile.

    Je préfère penser que plutôt que de donner dans le dogmatisme, genre "une méthode ne doit avoir que x lignes", il faut mieux laisser le choix au cerveau du programmeur, qui jugera d'après le contexte et la pertinence. Après tout, on paye le programmeur pour son cerveau, laissons-le s'en servir.

    A+
    Claude

  5. #105
    Membre du Club
    Homme Profil pro
    Enseignant Chercheur
    Inscrit en
    mai 2009
    Messages
    38
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 33
    Localisation : Congo-Kinshasa

    Informations professionnelles :
    Activité : Enseignant Chercheur
    Secteur : Enseignement

    Informations forums :
    Inscription : mai 2009
    Messages : 38
    Points : 65
    Points
    65
    Par défaut
    Citation Envoyé par Klaim Voir le message
    Meme question.

    En plus on ne fait ici pas la difference entre les commentaires explicitant le comportement et l'usage d'une interface et les commentaires dans l'implementation de cette interface. C'est tellement different que ca n'a presque rien a voir.
    1) La question est toujours d'actualité et le restera tant qu'on continuera à écrire du code. N'empêche, le débat ne devrait pas se limiter aux commentaires ! Il s'agira, en général, de se préoccuper de produire du code source de qualité. Par code de qualité, j'entend : lisible, compréhensible, basé sur les bonnes pratiques de dév, facile à maintenir. Les exigences de l'ingénierie logicielle d'aujourd'hui (équipe, travail collaboratif, dév par réutilisation, modèle open source, ...) n'en attendent pas moins.

    2) Les commentaires, ça reste les commentaires, sur une interface, dans une implémentation et partout ailleurs. La question c'est le bien-fondé des commentaires face à la compréhensibilité du code, pas l'endroit où << ils devraient apparaître >>.

  6. #106
    Membre expert

    Avatar de germinolegrand
    Homme Profil pro
    Développeur de jeux vidéo
    Inscrit en
    octobre 2010
    Messages
    738
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France, Puy de Dôme (Auvergne)

    Informations professionnelles :
    Activité : Développeur de jeux vidéo
    Secteur : Tourisme - Loisirs

    Informations forums :
    Inscription : octobre 2010
    Messages : 738
    Points : 3 891
    Points
    3 891
    Par défaut
    Citation Envoyé par bottus
    Je pense que l'interet des commentaires se fait sentir lorsque l'on code de façon impérative.
    Lorsque l'on code en c++, le simple fait d'être dans une classe et pas dans une autre nous donne deja une vision bien précise du "sur quoi ce code va t'il avoir de l'impact". Ensuite avec des méthodes et attributs bien nommés, on s'en sort très bien pour peu que ce soit propre.
    Je pense par contre que l'utilité des commentaires est présente avec des langages comme du C qui nécessite selon moi de l'explication, au moins pour faciliter son évolutivité.
    Mettre en comparaison deux langages sur le critère du paradigme, alors même que l'un est plutôt mono-paradigme (C = globalement impératif, pardonnez moi si jamais j'ai dit une bêtise...) et l'autre très foncièrement multiparadigme (C++ != POO, loin de là : impératif, fonctionnel, générique, etc.), est un peu absurde.

    Citation Envoyé par Paul TOTH Voir le message
    je pense très exactement le contraire.

    dans un code C procédural il est relativement facile de savoir ce qu'on fait, alors qu'avec une arborescence objet C++ avec des classes virtuelles, des generics et cie, on a tout un tas de code très abstrait dont on ne sait à priori pas à quoi il sert, comment il est dérivé et/ou de quoi on dérive. On n'a pas de vision claire des événements de leur déclencheurs ou de l'ordre de leur déclenchement si toutefois il est défini.
    Plus d'éléments de langage amène en effet plus de fouillis intrinsèquement. Et pourtant, une bonne combinaison de ces paradigmes peut rendre le code plus explicite de lui-même sans qu'on ait à y réfléchir 3h. C'est un peu une des raisons qui me poussent à préférer le C++11 (je ne parle pas du 03 dans lequel j'admets volontiers une complexité de lisibilité du code) au C. Par contre j'admets également volontiers qu'un C bien commenté est très lisible.

    Un petit exemple pour la route tiré tout droit du code de mon serveur (tous droits réservés blabla, non osef le code est tellement clair que j'aurais l'impression de mettre un copyright sur quelque chose de trivial ^^):
    Code c++ : Sélectionner tout - Visualiser dans une fenêtre à part
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
     
    std::vector<ServerId> ConnectionGraph::findUnderconnectedServers(unsigned int minimum) const
    {
        std::vector<ServerId> underconnected;
     
        for(auto& server : m_graph)
        {
            if(server.second.size() < minimum)
                underconnected.push_back(server.first);
        }
     
        return underconnected;
    }
    J'ose supposer que ce code ne nécessite pas de commentaires... Je l'espère pour mes collègues en tout cas, et je vais être fixé en voyant vos réponses de toute façon .

  7. #107
    Membre chevronné

    Homme Profil pro
    Développeur .NET
    Inscrit en
    juillet 2009
    Messages
    966
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 34
    Localisation : France, Rhône (Rhône Alpes)

    Informations professionnelles :
    Activité : Développeur .NET

    Informations forums :
    Inscription : juillet 2009
    Messages : 966
    Points : 2 006
    Points
    2 006
    Par défaut
    Citation Envoyé par ClaudeBg Voir le message
    Code : Sélectionner tout - Visualiser dans une fenêtre à part
    1
    2
    3
    4
    5
    6
    7
    // <summary>
            /// Calcul du taux de TVA
            /// </summary>
            /// <param name="pValeurHt">valeur Hors taxe</param>
            /// <param name="pTaux">taux de tva</param>
            /// <returns>valeur Hors taxe * le taux de tva</returns>
            public decimal CalculTVA(decimal pValeurHt,decimal pTaux)
    Code : Sélectionner tout - Visualiser dans une fenêtre à part
    1
    2
    3
    4
    5
    6
    7
     
           private decimal CalculTVA(decimal pValeurHt,decimal pTaux)
            {
                decimal lValeurCalculer;                     // initialisations
                lValeurCalculer = pValeurHt * pTaux;         // valeur TVA
                return lValeurCalculer;                      // retour TVA
            }
    Je veux les commentaires, je lis à droite, je veux le code, je lis à gauche.
    et bien je trouve ta façons de commenter tres inteligente.

    par contre je ne suis pas d'accord avec le faite de pensée que les entetes ne font pas partie des commentaires.
    moi pour ma part, je regarde toujours se doit faire une fonction avant meme de regarder comment elle le fait.

    d'ailleurs je met toujours un commentaire en entete bien que je ne génere pas de documentation. c'est une habitude que j'ai pris et qui je trouve permet de gagner du temps dans la compréhension d'une fonction.
    un jour, quelqu'un a dit quelque chose...

  8. #108
    Membre éprouvé
    Profil pro
    Inscrit en
    juin 2008
    Messages
    598
    Détails du profil
    Informations personnelles :
    Localisation : Belgique

    Informations forums :
    Inscription : juin 2008
    Messages : 598
    Points : 1 034
    Points
    1 034
    Par défaut
    Salut
    -----

    et bien je trouve ta façons de commenter tres inteligente
    Je te remercie du compliment

    par contre je ne suis pas d'accord avec le faite de pensée que les entetes ne font pas partie des commentaires.
    moi pour ma part, je regarde toujours se doit faire une fonction avant meme de regarder comment elle le fait.
    Je me suis mal expliqué car je suis entièrement d'accord avec ce que tu dis.

    Je ne parlais pas de ceci :

    // Ceci est un commentaire décrivant MyMethod
    private MyMethod ()
    {
    ...
    }
    Je procède également comme ça pour les commentaires "généraux".

    Je parlais de ceci :

    Code : Sélectionner tout - Visualiser dans une fenêtre à part
    1
    2
    3
    4
    5
    6
    7
    / <summary>
            /// Calcul du taux de TVA
            /// </summary>
            /// <param name="pValeurHt">valeur Hors taxe</param>
            /// <param name="pTaux">taux de tva</param>
            /// <returns>valeur Hors taxe * le taux de tva</returns>
            public decimal CalculTVA(decimal pValeurHt,decimal pTaux)
    Les balises summary, param, para, return etc sont des balises qui permettent à Visual Studio de générer le fichier XML de documentation directement à partir des informations fournies dans ces balises.

    Dès lors, lorsque l'intervenant expliquait que ça ne servait à rien dans le cas cité, il signifiait en fait que la documentation du programme ne servait à rien. Ça revient à élargir le débat "pour ou contre les commentaires" au débat "pour ou contre les documentations".

    Ces balises donnent donc des informations genre "commentaires" lorsqu'on les lit mais en fait ne sont pas de simples commentaires.

    Et, évidemment, étant défenseur des commentaires, tu penses bien que je suis également défenseur des documentations (j'utilise les docs générées automatiquement à destination des développeurs mais aussi des docs écrites "à la main" destinées aux utilisateurs).

    J'espère que comme ça je me suis montré plus clair.

    J'ose supposer que ce code ne nécessite pas de commentaires.
    Ce n'est pas parce qu'on peut comprendre sans commentaire qu'un commentaire n'est ni utile ni le bienvenu. La question à se poser est plutôt l'inverse: qu'est-ce qui dérange si j'ajoute un commentaire?

    Et puis, dans un monde où les développeurs sont souvent contraints de s'adapter à des tas d'environnements, ce qui semble évident à un dont le langage et la cible sont la spécialité risque de ne pas l'être pour un autre qui doit peut-être modifier occasionnellement un programme dont le langage n'est pas son langage habituel.

    Comme l'a dit un intervenant de façon fort pertinente: il est plus simple d'écrire du code que de le lire, celui qui écrit est donc en général mal placé pour savoir si le code qu'il écrit sera "évident" ou non pour d'autres.

    A+
    Claude

  9. #109
    Expert éminent sénior
    Profil pro
    Inscrit en
    décembre 2007
    Messages
    6 680
    Détails du profil
    Informations personnelles :
    Localisation : France, Hérault (Languedoc Roussillon)

    Informations forums :
    Inscription : décembre 2007
    Messages : 6 680
    Points : 30 994
    Points
    30 994
    Par défaut
    Citation Envoyé par ClaudeBg Voir le message
    (.../...)Pour le découpage du code, moi je suis pour scinder le code dans le sens de factorisation. C'est à dire que je scinde si les parties factorisées on un intérêt à être ré-utilisées plusieurs fois à partir de plusieurs endroits différents. Si le but est de couper une méthode de 100 lignes en 10 méthodes de 10 lignes sans objectif de réutilisation, je trouve ça nuisible, pour les raisons suivantes .../...)
    +1000 : c'est le "do not repeat yourself".

    Bon, parfois, on va découper quand même parceque ça devient absolument monstrueux. Genre, j'avais un algo en 3 boucles gigantesques, j'ai découpé mon code en 3 morceaux, hein, même si ça n'était réutilisé nulle part ailleurs, et que les 3 boucles se suivaient bêtement.

    Mais 3 boucles ridicules, je met ça en bloc(tant qu'il ne faut pas réutiliser). Ca permet, comme tu le dis, de mieux suivre le déroulement complet du code.
    Les 4 règles d'airain du développement informatique sont, d'après Michael C. Kasten :
    1)on ne peut pas établir un chiffrage tant qu'on a pas finalisé la conception
    2)on ne peut pas finaliser la conception tant qu'on a pas complètement compris toutes les exigences
    3)le temps de comprendre toutes les exigences, le projet est terminé
    4)le temps de terminer le projet, les exigences ont changé
    Et le serment de non-allégiance :
    Je promets de n’exclure aucune idée sur la base de sa source mais de donner toute la considération nécessaire aux idées de toutes les écoles ou lignes de pensées afin de trouver celle qui est la mieux adaptée à une situation donnée.

  10. #110
    Expert éminent sénior
    Avatar de Paul TOTH
    Homme Profil pro
    Freelance
    Inscrit en
    novembre 2002
    Messages
    8 322
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 52
    Localisation : France, Paris (Île de France)

    Informations professionnelles :
    Activité : Freelance
    Secteur : High Tech - Éditeur de logiciels

    Informations forums :
    Inscription : novembre 2002
    Messages : 8 322
    Points : 26 957
    Points
    26 957
    Par défaut
    Citation Envoyé par germinolegrand Voir le message
    Code c++ : Sélectionner tout - Visualiser dans une fenêtre à part
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
     
    std::vector<ServerId> ConnectionGraph::findUnderconnectedServers(unsigned int minimum) const
    {
        std::vector<ServerId> underconnected;
     
        for(auto& server : m_graph)
        {
            if(server.second.size() < minimum)
                underconnected.push_back(server.first);
        }
     
        return underconnected;
    }
    J'ose supposer que ce code ne nécessite pas de commentaires... Je l'espère pour mes collègues en tout cas, et je vais être fixé en voyant vos réponses de toute façon .
    là dessus j'ajouterais bien un commentaire expliquant pourquoi on a besoin de cette liste. En outre, le "pourquoi" est souvent intéressant pour comprendre le "comment". Ce commentaire pouvant être selon le cas sur la méthode ou sur son appel si celui-ci est mutlifonctionnel.

    D'ailleurs le pourquoi permet aussi de corriger un code artificiellement complexe car le programmeur était débutant ou juste très fatigué quand il a pondu le code...sans le pourquoi on peut se dire que ce code alambiqué cache une subtilité qui ne saute pas aux yeux du premier coup.
    Developpez.com: Mes articles, forum FlashPascal
    Entreprise: Execute SARL
    Le Store Excute Store

  11. #111
    Rédacteur
    Avatar de Nathanael Marchand
    Homme Profil pro
    Expert .Net So@t
    Inscrit en
    octobre 2008
    Messages
    3 615
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 35
    Localisation : France, Paris (Île de France)

    Informations professionnelles :
    Activité : Expert .Net So@t
    Secteur : Conseil

    Informations forums :
    Inscription : octobre 2008
    Messages : 3 615
    Points : 8 054
    Points
    8 054
    Par défaut
    Citation Envoyé par Paul TOTH Voir le message
    là dessus j'ajouterais bien un commentaire expliquant pourquoi on a besoin de cette liste. En outre, le "pourquoi" est souvent intéressant pour comprendre le "comment". Ce commentaire pouvant être selon le cas sur la méthode ou sur son appel si celui-ci est mutlifonctionnel.

    D'ailleurs le pourquoi permet aussi de corriger un code artificiellement complexe car le programmeur était débutant ou juste très fatigué quand il a pondu le code...sans le pourquoi on peut se dire que ce code alambiqué cache une subtilité qui ne saute pas aux yeux du premier coup.
    Pas d'accord ! C'est pas à celui qui rédige une méthode de dire pourquoi il met à disposition la méthode.
    "J'ai fait cette méthode car j'en ai besoin dans l'écran titi" Celui qui passe derrière et qui l'utilise aussi va rajouter son grain ? "ah ben moi je l'utilise dans l'écran toto", c'est juste ingérable...
    Avec les IDE modernes on est quand même plus tranquille que sur bloc note. Si je veux savoir qui appelle ma méthode j'peux avoir l'arborescence de toutes les méthodes. C'est quand même moins bricolage...

    Pareil pour le "ca permet de définir ce qu'on attend des paramètres et des cas limites"
    Non je suis désolé ce genre de choses ca se code : si restriction il y a sur les paramètres on teste clairement au début. Est ce que ca doit être dans la doc : oui, un commentaire : non

  12. #112
    Expert éminent sénior
    Avatar de Paul TOTH
    Homme Profil pro
    Freelance
    Inscrit en
    novembre 2002
    Messages
    8 322
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 52
    Localisation : France, Paris (Île de France)

    Informations professionnelles :
    Activité : Freelance
    Secteur : High Tech - Éditeur de logiciels

    Informations forums :
    Inscription : novembre 2002
    Messages : 8 322
    Points : 26 957
    Points
    26 957
    Par défaut
    Citation Envoyé par Nathanael Marchand Voir le message
    Pas d'accord ! C'est pas à celui qui rédige une méthode de dire pourquoi il met à disposition la méthode.
    il conçoit donc des méthodes pour le plaisir, elles n'ont pas de finalité en fait. j'ai écrit une méthode à toi de voir si elle peut te servir, moi je fais rien avec, je pisse de lignes c'est tout

    Citation Envoyé par Nathanael Marchand Voir le message
    "J'ai fait cette méthode car j'en ai besoin dans l'écran titi" Celui qui passe derrière et qui l'utilise aussi va rajouter son grain ? "ah ben moi je l'utilise dans l'écran toto", c'est juste ingérable...
    Avec les IDE modernes on est quand même plus tranquille que sur bloc note. Si je veux savoir qui appelle ma méthode j'peux avoir l'arborescence de toutes les méthodes. C'est quand même moins bricolage...

    Pareil pour le "ca permet de définir ce qu'on attend des paramètres et des cas limites"
    Non je suis désolé ce genre de choses ca se code : si restriction il y a sur les paramètres on teste clairement au début. Est ce que ca doit être dans la doc : oui, un commentaire : non
    l'exemple donné est clairement une méthode fonctionnelle, si je dois à chaque méthode faire appel à la recherche de tous les appels pour déterminer à quoi elle peut bien servir, j'ai pas fini !
    Developpez.com: Mes articles, forum FlashPascal
    Entreprise: Execute SARL
    Le Store Excute Store

  13. #113
    Rédacteur
    Avatar de Nathanael Marchand
    Homme Profil pro
    Expert .Net So@t
    Inscrit en
    octobre 2008
    Messages
    3 615
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 35
    Localisation : France, Paris (Île de France)

    Informations professionnelles :
    Activité : Expert .Net So@t
    Secteur : Conseil

    Informations forums :
    Inscription : octobre 2008
    Messages : 3 615
    Points : 8 054
    Points
    8 054
    Par défaut
    Citation Envoyé par Paul TOTH Voir le message
    l'exemple donné est clairement une méthode fonctionnelle, si je dois à chaque méthode faire appel à la recherche de tous les appels pour déterminer à quoi elle peut bien servir, j'ai pas fini !
    Le à quoi elle sert doit être dans le nom de la méthode. Le pourquoi elle a été codée, on s'en fiche en fait. C'est soit que quelqu'un en a eu besoin ou a prévu qu'il en aurait besoin (dans la conception d'une API par exemple).

  14. #114
    Rédacteur
    Avatar de pseudocode
    Homme Profil pro
    Architecte système
    Inscrit en
    décembre 2006
    Messages
    10 062
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 49
    Localisation : France, Hérault (Languedoc Roussillon)

    Informations professionnelles :
    Activité : Architecte système
    Secteur : Industrie

    Informations forums :
    Inscription : décembre 2006
    Messages : 10 062
    Points : 15 892
    Points
    15 892
    Par défaut
    Citation Envoyé par Nathanael Marchand Voir le message
    Non je suis désolé ce genre de choses ca se code : si restriction il y a sur les paramètres on teste clairement au début. Est ce que ca doit être dans la doc : oui, un commentaire : non
    Bof. L'un n'empêche pas l'autre.

    Code C++ : Sélectionner tout - Visualiser dans une fenêtre à part
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    /* Cette fonction retourne la liste des serveurs dont ????? est inférieur au paramètre "minimum"
     * Ces serveurs sont considérés comme Underconnected, c'est à dire ??????.
     */
    std::vector<ServerId> ConnectionGraph::findUnderconnectedServers(unsigned int minimum) const
    {
        std::vector<ServerId> underconnected;
     
        // on fait un parcours exhaustif du graphe pour trouver les serveurs. Algorithme en O(N).
        // Not Thread-Safe: Ne gère pas les accès concurrents a m_graph.
     
        for(auto& server : m_graph)
        {
            if(server.second.size() < minimum)
                underconnected.push_back(server.first);
        }
     
        return underconnected;
    }
    ALGORITHME (n.m.): Méthode complexe de résolution d'un problème simple.

  15. #115
    Membre expert

    Avatar de germinolegrand
    Homme Profil pro
    Développeur de jeux vidéo
    Inscrit en
    octobre 2010
    Messages
    738
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France, Puy de Dôme (Auvergne)

    Informations professionnelles :
    Activité : Développeur de jeux vidéo
    Secteur : Tourisme - Loisirs

    Informations forums :
    Inscription : octobre 2010
    Messages : 738
    Points : 3 891
    Points
    3 891
    Par défaut
    l'exemple donné est clairement une méthode fonctionnelle, si je dois à chaque méthode faire appel à la recherche de tous les appels pour déterminer à quoi elle peut bien servir, j'ai pas fini !
    A quoi elle sert ? c'est marqué dans son prototype : suffit de lire.
    Comment le fait-elle ? c'est marqué dans le code : suffit de lire.

    Quand je dis suffit de lire c'est parce que je cherche à ce que le code soit le plus expressif possible et que sa lecture soit quasi-litérale.

    Écrire un tel code ne demande aucune réflexion supplémentaire pour le rendre plus expressif, cela se fait naturellement (avec l'habitude évidemment je ne vous dis pas que quelqu'un qui débute en C++11 en sera capable immédiatement).

    C'est cela que je travaille et que je cultive : l'expressivité du code. Trouver des méthodes qui rendent le code plus expressif que l'anglais qui composerait le commentaire.

    Quand à savoir à quelles fins seront utilisées les méthodes de ma classes, cela ne me regarde pas dans la mesure où la seule chose qu'il me faille garantir c'est que l'objet soit constamment dans un état valide.

    Certes je ne crée pas une fonctionnalité sans but, et même généralement je l'ajoute parce que j'ai déjà écrit un code qui l'utilise, mais je veille toujours à ce que la fonctionnalité que j'ajoute pour un besoin externe soit cohérente avec le fonctionnement interne.

    --------

    Par ailleurs, je note que l'on cite comme argument pour le parti du moindre-commentaire un bon nommage des fonctions, je trouve que cet argument est fallacieux car il offre de grosses opportunités de critique (on en arrive notamment aux noms trop long et imbitables).

    Pour moi une fonction bien nommée ne suffit pas à l'auto-documenter. Ça suffit à peine à deviner (très rarement avec exactitude) ce qu'elle fait.
    Ce qui fait la documentation d'une fonction, c'est son prototype au grand complet. Si c'est une méthode, il faut également la prendre dans le contexte de sa classe. Ainsi, outre le fait de donner un nom à la fois clair et simple, il est absolument impératif de soigner les noms des arguments, les types des arguments, ainsi que le type de retour. Ne pas faire de redondance entre le nom de la fonction et les autres informations sus-citées, ça alourdit inutilement le code. Garder absolument une cohérence avec les autres méthodes de la classe si c'est une méthode.

    La même chose s'applique aux classes, transposé à un niveau au dessus (type des attributs, simplicité et clarté des moyens d'utilisation et d'interaction avec les autres classes).

    Le nom d'une variable/argument/attribut définit ce qu'elle contient ou de ce qu'elle représente. Son type définit sa sémantique d'utilisation et ses limites.

    Un exemple avec le unsigned int minimum en argument.
    Le nom tout d'abord minimum définit ce qu'il représente, en corrélation avec le nom de la fonction : le nombre ("int") "minimum" de connexions ("connected") en dessous ("Under") duquel les serveurs ("Servers") du graphe de connexion ("ConnexionGraph::" voilà pour le contexte ) sont sous-connectés ("Underconnected").
    Le type ici unsigned int indique que le critère "minimum" est un nombre ("int") de connexions qui est positif ("unsigned").

    Et je n'ai extrait ici que les informations qui concernent l'argument de la fonction !

    Ceci montre deux choses : qu'on peut en apprendre beaucoup (vraiment beaucoup même) sur une fonction rien qu'en analysant son prototype, et que le français est un très mauvais choix de langue pour commenter un code au vu des nombreuses répétitions et tournures alambiquées nécessaires (sans compter les accents).
    Mais l'anglais n'en est pas pour autant exempt (c'est mieux que le français), et il se trouve que le langage C++11 (je l'apprécie beaucoup pour ça) offre la possibilité d'être très expressif en restant simple.

    Ce n'est pas parce qu'on peut comprendre sans commentaire qu'un commentaire n'est ni utile ni le bienvenu. La question à se poser est plutôt l'inverse: qu'est-ce qui dérange si j'ajoute un commentaire?
    C'est de la paraphrase lors de l'écriture, c'est du bruit lors de la lecture. Tu as beau lire les commentaires pour savoir ce que fait un code (ou plutôt ce qu'il est censé faire), tu vas forcément devoir relire le code lui-même (d'autant plus si tu dois le débugger).
    Qui dit paraphraser dit écrire 2 fois. Qui dit écrire deux fois dit 2 fois plus de chances de se tromper quelque part.
    Pourquoi choisir un langage X plutôt que le langage C++11 pour commenter du code C++11 ? Personnellement je préfère lire du C++11 que du japonais (je n'ai rien contre les japonais mais mon code est fait pour être lu par des développeurs C++11, et il peut être lu autant par un japonais qu'un espagnol ou un français même si sa maîtrise de l'anglais n'est pas suffisante pour comprendre des commentaires explicatifs en anglais de haut vol).

  16. #116
    Nouveau Candidat au Club
    Inscrit en
    juillet 2010
    Messages
    11
    Détails du profil
    Informations forums :
    Inscription : juillet 2010
    Messages : 11
    Points : 0
    Points
    0
    Par défaut
    Ca résume un peu ce qui est dit dans ce bouquin, même s'ils mettent également en avant les commentaires: http://www.amazon.com/Art-Readable-C.../dp/0596802293

    Je pense que tous les développeurs devraient lire ce bouquin, à titre personnel, il a grandement améliorer la lisibilité et la maintenabilité de mon code !

  17. #117
    Inactif  


    Homme Profil pro
    Doctorant sécurité informatique — Diplômé master Droit/Économie/Gestion
    Inscrit en
    décembre 2011
    Messages
    9 013
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 28
    Localisation : France, Loire (Rhône Alpes)

    Informations professionnelles :
    Activité : Doctorant sécurité informatique — Diplômé master Droit/Économie/Gestion
    Secteur : Enseignement

    Informations forums :
    Inscription : décembre 2011
    Messages : 9 013
    Points : 22 975
    Points
    22 975
    Par défaut
    Bonjour,

    @germinolegrand : Il faut tout de même reconnaître que dès qu'on renvoit un pointeur ou une référence, il faut bien spécifier la façon de libérer la mémoire ( 4 choix possibles : delete, delete[], appeler une fonction spécifique, ne rien faire).
    Ensuite, le prototype ne suffit pas toujours à tout exprimer, que se passe-t-il en cas d'erreur ? Est-ce qu'il y a des spécificités ?
    De plus, sommes-nous sûr qu'un autre développeur comprendra le prototype de la même manière que nous ?
    Un commentaire pour la documentation me semble donc obligatoire pour une très grande majorité des fonctions.

    Citation Envoyé par germinolegrand Voir le message
    C'est de la paraphrase lors de l'écriture, c'est du bruit lors de la lecture. Tu as beau lire les commentaires pour savoir ce que fait un code (ou plutôt ce qu'il est censé faire), tu vas forcément devoir relire le code lui-même (d'autant plus si tu dois le débugger).
    Qui dit paraphraser dit écrire 2 fois. Qui dit écrire deux fois dit 2 fois plus de chances de se tromper quelque part.
    Sûrement pas, l'encapsulation est un des principe élémentaire en C++, on a pas à savoir comment il fait, juste à savoir comment l'utiliser, ce qu'il fait et éventuellement sa complexité.
    On ne doit pas relire les codes, on doit lire la documentation générée à partir des commentaires.
    Si on doit relire ton code pour l'utiliser, c'est qu'il y a un gros problème.

  18. #118
    Expert éminent sénior
    Avatar de Paul TOTH
    Homme Profil pro
    Freelance
    Inscrit en
    novembre 2002
    Messages
    8 322
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 52
    Localisation : France, Paris (Île de France)

    Informations professionnelles :
    Activité : Freelance
    Secteur : High Tech - Éditeur de logiciels

    Informations forums :
    Inscription : novembre 2002
    Messages : 8 322
    Points : 26 957
    Points
    26 957
    Par défaut
    Citation Envoyé par germinolegrand Voir le message
    A quoi elle sert ? c'est marqué dans son prototype : suffit de lire.
    Comment le fait-elle ? c'est marqué dans le code : suffit de lire.
    Non, je ne sais toujours pas à quoi peu servir une liste de serveurs dits "sous-connectés". terme qui pourrait laisser penser qu'on cherche des serveurs sous-utilisés, une question d'optimisation peut-être mais je ne peux que le supposer.

    Hors contexte (car ce nom a peut-être un intérêt dans son contexte), j'aurais appelé la méthode à base de LessConnexionThan qui est ce que fait réellement le code si j'en crois tes commentaires. A la lecture par contre, server.second et server.first me font penser à une liste chaînée utilisée très bizarrement puisqu'on teste "second" pour récupérer "first".

    Citation Envoyé par germinolegrand Voir le message
    Quand je dis suffit de lire c'est parce que je cherche à ce que le code soit le plus expressif possible et que sa lecture soit quasi-litérale.

    Écrire un tel code ne demande aucune réflexion supplémentaire pour le rendre plus expressif, cela se fait naturellement (avec l'habitude évidemment je ne vous dis pas que quelqu'un qui débute en C++11 en sera capable immédiatement).
    et bien justement, les développeurs ne sont pas toujours expert dans le langage qu'ils doivent maintenir (demande leur avis à tous les développeurs C# à qui on a demandé de traduire du code Delphi).

    Personnellement je lis bcp de C++ pour le traduire en Pascal (Delphi) ce qui me donne une connaissance très relative du C++ et des efforts constants pour le comprendre, dans 90% des cas c'est relativement simple, et il reste 10% de code abscons à base de conversion de type, de macro, de generic et cie qui rendent la lecture des plus confuse.

    Citation Envoyé par Oxydium Voir le message
    Ca résume un peu ce qui est dit dans ce bouquin, même s'ils mettent également en avant les commentaires: http://www.amazon.com/Art-Readable-C.../dp/0596802293

    Je pense que tous les développeurs devraient lire ce bouquin, à titre personnel, il a grandement améliorer la lisibilité et la maintenabilité de mon code !
    est il écrit en C++11 ?
    Developpez.com: Mes articles, forum FlashPascal
    Entreprise: Execute SARL
    Le Store Excute Store

  19. #119
    Membre expert

    Avatar de germinolegrand
    Homme Profil pro
    Développeur de jeux vidéo
    Inscrit en
    octobre 2010
    Messages
    738
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France, Puy de Dôme (Auvergne)

    Informations professionnelles :
    Activité : Développeur de jeux vidéo
    Secteur : Tourisme - Loisirs

    Informations forums :
    Inscription : octobre 2010
    Messages : 738
    Points : 3 891
    Points
    3 891
    Par défaut
    Citation Envoyé par Neckara Voir le message
    Bonjour,

    @germinolegrand : Il faut tout de même reconnaître que dès qu'on renvoit un pointeur ou une référence, il faut bien spécifier la façon de libérer la mémoire ( 4 choix possibles : delete, delete[], appeler une fonction spécifique, ne rien faire).
    Ensuite, le prototype ne suffit pas toujours à tout exprimer, que se passe-t-il en cas d'erreur ? Est-ce qu'il y a des spécificités ?
    De plus, sommes-nous sûr qu'un autre développeur comprendra le prototype de la même manière que nous ?
    Un commentaire pour la documentation me semble donc obligatoire pour une très grande majorité des fonctions.
    Si tu renvoie une référence, je ne voit pas comment tu peux imaginer devoir faire un delete dessus (d'accord je trolle, je suppose que tu parles des références qui transfèrent une responsabilité ? dans ce cas cf les pointeurs nu).
    Si tu renvoies des pointeurs nus pour transférer une responsabilité, il ne faut t'en prendre qu'à toi-même, le RAII est là pour ça, il fait ça proprement et clairement (le RAII ne se limite pas aux pointeurs intelligents).

    Citation Envoyé par Neckara Voir le message
    Sûrement pas, l'encapsulation est un des principe élémentaire en C++, on a pas à savoir comment il fait, juste à savoir comment l'utiliser, ce qu'il fait et éventuellement sa complexité.
    On ne doit pas relire les codes, on doit lire la documentation générée à partir des commentaires.
    Si on doit relire ton code pour l'utiliser, c'est qu'il y a un gros problème.
    Tu dois le relire pour debugger, nuance.
    Pour l'utiliser tu utilise la doc pas les commentaires. Et ce qui fait office de doc c'est le prototype + la déclaration de la classe (élément absent du code d'exemple).

    Citation Envoyé par Paul TOTH
    A la lecture par contre, server.second et server.first me font penser à une liste chaînée utilisée très bizarrement puisqu'on teste "second" pour récupérer "first".
    Il manque là aussi également la déclaration de la classe pour avoir accès au type de server (le type fournit justement ce genre d'informations). m_servers est une map, server est un pair qui a donc deux membres, first pour la clé et second pour la valeur (qui est ici une liste de connexions).
    Je reconnais très volontiers ce défaut à std::map et std::pair .

    et bien justement, les développeurs ne sont pas toujours expert dans le langage qu'ils doivent maintenir
    Justement, je vise à ce que ce code soit lisible par un débutant à défaut d'être réalisable par lui.

  20. #120
    Modérateur
    Avatar de Rayek
    Homme Profil pro
    Développeur informatique
    Inscrit en
    mars 2005
    Messages
    5 235
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 48
    Localisation : France, Haute Savoie (Rhône Alpes)

    Informations professionnelles :
    Activité : Développeur informatique
    Secteur : High Tech - Éditeur de logiciels

    Informations forums :
    Inscription : mars 2005
    Messages : 5 235
    Points : 8 471
    Points
    8 471
    Par défaut
    Un code "bien écrit" pour l'un ne l'est peut être pas pour les autres, le seul moyen pour que tout le monde se comprenne reste les commentaires.

    A méditer
    Modérateur Delphi

    Le guide du bon forumeur :
    __________
    Rayek World : Youtube Facebook

Discussions similaires

  1. Code Java bien écrit ?
    Par abysr dans le forum Débuter avec Java
    Réponses: 4
    Dernier message: 24/03/2015, 17h17
  2. Un code bien écrit a-t-il besoin des commentaires ?
    Par Hinault Romaric dans le forum Actualités
    Réponses: 334
    Dernier message: 19/07/2013, 15h22
  3. Un code bien commenté remplace-t-il une documentation? (+ gestion doc en entreprise)
    Par _skip dans le forum Débats sur le développement - Le Best Of
    Réponses: 30
    Dernier message: 13/01/2010, 13h12
  4. [Toutes versions] Identifier la base ACCESS où le code est écrit
    Par sl.info dans le forum VBA Access
    Réponses: 4
    Dernier message: 07/05/2009, 17h23
  5. [Système] Exécution code php écrit via fwrite()
    Par Torpedox dans le forum Langage
    Réponses: 4
    Dernier message: 26/01/2007, 18h09

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