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 :

En programmation, des variables bien nommées valent mieux qu’un bon commentaire


Sujet :

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

  1. #21
    Membre expérimenté
    Profil pro
    Inscrit en
    Février 2004
    Messages
    1 824
    Détails du profil
    Informations personnelles :
    Localisation : France

    Informations forums :
    Inscription : Février 2004
    Messages : 1 824
    Points : 1 544
    Points
    1 544
    Par défaut
    Il faut faire les deux mais à juste mesure et dans la limite du possible, on sait tous qu'un code propre, clair, net, concis, performant et sécurisé n'est jamais le fait du premier jet avec ses interrogations, ni produit dans des périodes de stress où le doute interne et le feu externe et la pression sont omniprésents.

    En général on fait "pour que ça marche" pour valider un concept / une architecture. Une fois le concept / l'architecture validée, on fait "pour que ça marche mieux". Puis on fait "pour que ça marche pareil, mais plus sécurisé". Une fois les performances validées, on nettoie mais en général avant cette dernière phase, comme ça n'est pas demandé directement par le client, on est affecté à un autre projet, une autre mission.

    Cette période de nettoyage est vu par la plupart de nos décideurs comme improductive et consommatrice de temps et donc d'argent, tout comme la phase de documentation soit dit en passant, on a tendance à faire ça lorsqu'il y a un audit qui pointe le bout de son nez, pas pour finaliser un projet.

    Pourtant elle est bien réellement productive, mais à moyen / long terme. On peut penser qu'un cuisto n'est pas productif lorsqu'il nettoie sa cuisine et sort les poubelles au lieu de préparer des trucs à vendre et donc à acheter sur le tas, sauf que s'il ne le faisait pas, comment se passerait la journée du lendemain qui commencera dans un merdier ambiant avec l'odeur qui va avec ?

    Par ailleurs, parfois un schéma vaut mieux qu'un long discours, d'où la nécessité d'un lien plutôt que 15 lignes de commentaires où on sent bien que celui qui l'a écrit s'embrouille tout seul face à la contrainte de l'unique langue qui n'aura pour terminaison que d'embrouiller davantage son lecteur.

    Enfin, les commentaires sont également utilisés pour la sécurité juridique, une petite faute de grammaire ou d'orthographe par ci par là peut justifier un copier /coller illicite devant des autorités. C'est ce que m'a conseillé de faire mon avocate spécialisé dans les droits juridiques et numériques.
    "Heureusement qu'il y avait mon nez, sinon je l'aurais pris en pleine gueule" Walter Spanghero

  2. #22
    Inactif  
    Profil pro
    Inscrit en
    Août 2008
    Messages
    238
    Détails du profil
    Informations personnelles :
    Localisation : France

    Informations forums :
    Inscription : Août 2008
    Messages : 238
    Points : 620
    Points
    620
    Par défaut
    Le nommage ne remplacera jamais le pseudo-code. Je ne dis pas le commentaire mais bien le pseudo-code intégré au code source.
    Le pseudo-code est une plus-value car il est plus abstrait que le code lui-même d'une part et potentiellement plus riche d'information sur l'intention de l'auteur car c'est du texte libre.

    Les commentaires s'ajoutent comme autant de remarques utiles à éclairer sur le raisonnement de l'auteur en réponse au problème posé.


    Cette méthode a fait ses preuves et chacun est soulagé d'avoir à faire avec un code source qui respecte cette méthode.

    D'autre part, on ne commente jamais trop mais ce sont les commentaires contradictoires ou peu étayés qui nuisent.

  3. #23
    Membre expérimenté
    Profil pro
    Inscrit en
    Février 2004
    Messages
    1 824
    Détails du profil
    Informations personnelles :
    Localisation : France

    Informations forums :
    Inscription : Février 2004
    Messages : 1 824
    Points : 1 544
    Points
    1 544
    Par défaut
    Citation Envoyé par captaindidou Voir le message
    Le nommage ne remplacera jamais le pseudo-code. Je ne dis pas le commentaire mais bien le pseudo-code intégré au code source.
    Le pseudo-code est une plus-value car il est plus abstrait que le code lui-même d'une part et potentiellement plus riche d'information sur l'intention de l'auteur car c'est du texte libre.

    Les commentaires s'ajoutent comme autant de remarques utiles à éclairer sur le raisonnement de l'auteur en réponse au problème posé.


    Cette méthode a fait ses preuves et chacun est soulagé d'avoir à faire avec un code source qui respecte cette méthode.

    D'autre part, on ne commente jamais trop mais ce sont les commentaires contradictoires ou peu étayés qui nuisent.
    C'est pas faux, mais ça dépend des situations, quand c'est très abstrait, mieux vaut un schéma, quand c'est trop simpliste, mieux vaut ne pas commenter au risque de prendre le lecteur pour un "gaga".

    Ce n'est qu'une question de mesure, et de temps à y consacrer.
    "Heureusement qu'il y avait mon nez, sinon je l'aurais pris en pleine gueule" Walter Spanghero

  4. #24
    Rédacteur/Modérateur

    Avatar de yahiko
    Homme Profil pro
    Développeur
    Inscrit en
    Juillet 2013
    Messages
    1 423
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France, Alpes Maritimes (Provence Alpes Côte d'Azur)

    Informations professionnelles :
    Activité : Développeur

    Informations forums :
    Inscription : Juillet 2013
    Messages : 1 423
    Points : 8 699
    Points
    8 699
    Billets dans le blog
    43
    Par défaut
    Si on se donne la peine de lire l'article original et la refactorisation de l'auteur, il n'est pas si évident que cela que le code remanié soit si clair par rapport au code de départ.
    Remplacer une procédure, pas génialement écrite certes, mais qui est loin d'être indigeste, par l'usine à gaz qu'est sa classe avec toutes ses méthodes que l'auteur introduit dans son refactoring, juste pour séparer le nom d'un fichier de son répertoire... OMG...

    Du coup, ça ne donne pas envie de croire l'auteur sur paroles.

    Au niveau de l'argumentation assez fallacieuse, l'auteur tente de montrer que parce qu'il est possible d'écrire du code plus clair (aucun souci avec cette affirmation), alors les commentaires sont inutiles... C'est un peu comme mélanger les choux et les carottes. Avec ce genre de raisonnement on peut aussi dire que comme on peut bien commenter, il n'est pas nécessaire d'écrire du code clair. C'est absurde évidemment. Il faut à la fois écrire du code clair et bien commenter.

    Les commentaires sont utiles à partir du moment où on travaille en équipe (et même pour soi-même les commentaires peuvent parfois sauver plusieurs heures). D'autres ont bien expliqué cet aspect ici avant moi, tant mieux. Les commentaires donne une vision plus large que le code. Pour schématiser, les commentaires doivent expliquer le pourquoi, alors que le code s'occupe du comment.

    Aussi d'un point de vue plus pratique , les commentaires lorsqu'ils sont bien écrits permettent une lecture en diagonale sans avoir à se plonger dans le dur du code. Cela permet de gagner du temps dans la compréhension global d'une base de code.

    Bref, j'ai quand même un peu peur que cette idée de ne pas commenter le code ne devienne tendance auprès de jeunes développeurs qui pourraient y voire l'opportunité de faire l'impasse ce qui est souvent vu comme un fardeau et une tâche ingrate.
    Tutoriels et FAQ TypeScript

  5. #25
    Membre chevronné
    Homme Profil pro
    Développeur informatique
    Inscrit en
    Juillet 2007
    Messages
    884
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 42
    Localisation : France, Loire Atlantique (Pays de la Loire)

    Informations professionnelles :
    Activité : Développeur informatique
    Secteur : High Tech - Opérateur de télécommunications

    Informations forums :
    Inscription : Juillet 2007
    Messages : 884
    Points : 2 018
    Points
    2 018
    Par défaut
    Un bon code pour un débutant n'est pas un bon code pour un expert. Tout code doit contenir du commentaire mais pas dans les même proportion.

    Un débutant a besoin de beaucoup de commentaire pour pouvoir se relire. Un expert a besoin de code concis pour pouvoir lire vite son code.

    Dans du code professionnel de haut niveau (Noyau Linux par exemple) il vaut mieux avoir du code en anglais pour une relecture international avec des noms de variable assez courte quand elles ont une porté courte mais utilisant les abréviation connu (Exp ptstr : pointeur sur la chaine de caractère "str"). Il faut aussi éviter le passage a la lignes excessif car on a besoin de pouvoir voir un maximum de code d'un coup d’œil.

    Cependant dans du code perso ou pour une application local il est plus simple d’écrire le code en français, avec des noms de variable un poil plus long et éviter trop de raccourcis de langages qui certes sont souvent plus optimisé mais parfois plus difficile a comprendre et pas toujours nécessaire dans des endroits non critiques. Un débutant apprécie aussi de voir plus d'espace pour bien séparé les blocs d'instrucions.

    Pour moi les commentaires se limitent au variables très globales (dont on ne peut pas toujours comprendre la signification sans voir le reste du programme), en début de programme ou au départ de boucle difficile a saisir rapidement et lors de raccourcis peu évident a comprendre (Comme les manipulation binaires "foo((a&0xff)>>2 | b);"). Mais le plus souvent en rajoutant une étape, on évite de calculer 2 fois une opération et on explicite un problème dans un nom de variable clair (1 pierre, 2 coup).
    Tout ce que j'écris est libre de droits (Licence CC0) et je vous incite à faire de même.

  6. #26
    Membre éprouvé
    Homme Profil pro
    Architecte de système d'information
    Inscrit en
    Août 2014
    Messages
    476
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 55
    Localisation : France, Ain (Rhône Alpes)

    Informations professionnelles :
    Activité : Architecte de système d'information

    Informations forums :
    Inscription : Août 2014
    Messages : 476
    Points : 1 042
    Points
    1 042
    Par défaut
    Je ne suis pas vraiment d'accord avec le gars - ca ne coute pas grand chose et j'ai tendance a coder en ecrivant sous forme de commentaires ce que j'ai a faire puis a completer en ajoutant des fonctions puis le code de ces fonctions etc (un peu a la facon d'ecrire des tests unitaires).
    Une fois que c'est fait je ne perds pas mon temps a supprimer les commentaires.
    Je ne sais pas ce qu'est cette mode de vouloir gratter quelques octets (ou comme en C#6 on ajoute de nouvelles syntaxes pour faire en 2 lignes ce qu'on faisait avant en 3 (property)). Ouep du gagne petit quand on sait qu'avec l'intellisence, resharper et autre on est toujours aidé au codage (et rassurez moi, les commentaires ne sont pas presents dans le code generé ? lol !).

    Derniere remarque, les commentaires sont generalement colorés differement du reste et je trouve que ca apporte justement une meilleure lisibilité du code.
    Quand je rentre dans du code sans commentaires (ce qui est produit par la plupart des developpeurs de nos jours), je trouve ça vraiment penible a lire (peut etre mes 25 ans de devpts qui me font dire cela).

  7. #27
    Membre confirmé Avatar de Darktib
    Profil pro
    Inscrit en
    Mai 2009
    Messages
    66
    Détails du profil
    Informations personnelles :
    Localisation : France

    Informations forums :
    Inscription : Mai 2009
    Messages : 66
    Points : 601
    Points
    601
    Par défaut
    Comme dit précédemment, les commentaires sont nécessaires dès que le code devient un peu compliqué (par ex implémentation d'un papier de recherche avec beaucoup de maths). Après, il ne faut pas en abuser...

    J'ai lu vite fait son article, et perso:
    - la première solution est du mauvais code.
    - la deuxième solution (avec la classe) est juste à jeter à la poubelle.

    IMHO, la bonne solution est une fonction de 3 lignes:
    Code : Sélectionner tout - Visualiser dans une fenêtre à part
    1
    2
    3
    4
    5
    6
    void splitPath(const std::string& path, std::string& outDir, std::string& outFile)
    {
        std::size_t sep = path.find_last_of("/\\");
        outDir = path.substr(0, sep > 1 ? sep : 1);
        outFile = path.substr(sep + 1);
    }
    Enfin, un truc que je fais beaucoup c'est de commenter les blocs de code dans une fonction de manière à ce que quelqu'un ne lisant que les commentaires puisse comprendre l'algorithme. Quand on bosse en équipe, c'est super pratique.

  8. #28
    Expert éminent
    Avatar de Matthieu Vergne
    Homme Profil pro
    Consultant IT, chercheur IA indépendant
    Inscrit en
    Novembre 2011
    Messages
    2 261
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France

    Informations professionnelles :
    Activité : Consultant IT, chercheur IA indépendant
    Secteur : High Tech - Éditeur de logiciels

    Informations forums :
    Inscription : Novembre 2011
    Messages : 2 261
    Points : 7 748
    Points
    7 748
    Billets dans le blog
    3
    Par défaut
    Perso, je remplacerai bien ton opérateur ternaire par un max(sep,1), qui me semble plus explicite.
    D'autres part : IHMO -> IMHO = In My Humble Opinion

    Je n'ai pas regardé l'article original, et donc de quoi il parle exactement, donc je ne me prononce que sur les principes.

    Citation Envoyé par Michael Guilloux Voir le message
    Qu’en pensez-vous ?
    Je suis entièrement d'accord, sans dire toutefois que les comentaires sont à bannir totalement (il ne faut jamais dire tout blanc ou tout noir). Si j'estime qu'il est bon de converger vers un code sans commentaires, passer par un code commenté ne me semble pas être critiquable, et au contraire parfois nécessaire pour ne pas s'"auto-censurer" (s'interdire de commenter alors qu'on sait que la conception aura besoin d'être révisée).

    Et je ne parle pas de documentation, visant à être lus sans se soucier du code (typiquement pour des API), mais bien de commentaires, qui sont là pour apparaître avec le code. Par exemple, quand cuicui78 parle de "bloc de commentaire qui explique ce qu'elle fait et pourquoi elle existe", pour moi c'est de l'ordre de la documentation. Soit tu lis ça et tu fais confiance et tu utilises, soit tu lis le code. Les commentaires en revanche, si tu ne lis pas le code qui va avec ça n'a aucun intérêt de les lire. Donc sans parler de syntaxe (on peut faire des commentaires en Javadoc comme de la documentation avec des /* ... */), la documentation doit être une description en langage naturel qui se suffit à elle-même, tout comme le code doit être une description en langage programmatique qui se suffit à lui-même. Les commentaires étant l'exception à la règle.

    Citation Envoyé par Michael Guilloux Voir le message
    Pourquoi devrait-on ou non ajouter des commentaires dans son code?
    Pour informer des subtilités, notamment des dépendances avec ce qui sort de la fonction concernée, typiquement des optimisations parce qu'on sait que cette fonction va être utilisée dans des contextes bien identifiés qu'il est donc important de préciser, pour éviter qu'un nouveau vienne modifier sans savoir mais en croyant bien faire.

    Citation Envoyé par micka132 Voir le message
    Je suis mitigé. Sur l'exemple qu'il donne autant à la lecture c'est plus concis, autant en cas de debug ça devient beaucoup plus embêtant puisqu'il faut faire beaucoup plus d'aller/retour entre toutes les méthodes qu'il créé.
    Ensuite je ne suis pas forcement fan de multiplier des méthodes de quelques lignes qui ne servent que dans le contexte particulier d'une autre méthode. On arrive vite à des fichiers énormes et on perd rapidement en clarté globale.

    Renommer les variables oui, remplacer tout par des méthodes bof, je ne parle même pas des nombreux cas où l'on doit ajouter un petit quelque chose qui fait que le nom que l'on a choisit n'est plus tout à fait juste...Et en cas d'oublie de refactoring du nom c'est bien pire qu'en cas d'oublie de modif de commentaire : soit on se fie au nom et c'est le drame, soit on "s'amuse" à naviguer vers chaque méthode pour vérifier qu'elle fait bien ce qu'elle dit.
    L'avantage de la découpe en fonctions, c'est que tu peux effectuer des tests unitaires sur chacune d'entre-elles, rendant la navigation manuelle quasi-inutile car tu as déjà les tests qui te montrent qu'elles font ce qu'elles doivent. Libre à toi en revanche d'ajouter un test manquant, et s'il ne passe pas alors d'analyser la méthode en question. Enfin, avec des IDE comme Eclipse pour Java, tu navigues dans tes fonctions sans difficultés. CTRL+clic ou F3 pour aller dedans, Alt+gauche pour revenir.

    Un fichier de code n'est pas un roman : il n'a pas vocation a être lu dans son ensemble. Sauf si tu fais de l'analyse de code, mais là c'est ton boulot que d'aller en profondeur, quel que soit le code en question, et donc tu n'as pas à te prononcer sur comment le code que tu dois analyser devrait être.
    Site perso
    Recommandations pour débattre sainement

    Références récurrentes :
    The Cambridge Handbook of Expertise and Expert Performance
    L’Art d’avoir toujours raison (ou ce qu'il faut éviter pour pas que je vous saute à la gorge {^_^})

  9. #29
    Membre émérite
    Inscrit en
    Janvier 2006
    Messages
    719
    Détails du profil
    Informations forums :
    Inscription : Janvier 2006
    Messages : 719
    Points : 2 712
    Points
    2 712
    Par défaut Portée
    Avant de se poser la question du nom d'une variable et de la nécessité ou non de la commenter, je crois qu'il est bien plus important de définir dès le départ sa portée.
    Or j'ai fait une recherche dans l'article, le mot "scope" n’apparait que dans un ou deux commentaires, pas dans l'article lui-même.

    Récemment j'ai dû aider un débutant Python, langage que je connais mal mais bien sûr basé sur un paradigme classique (objet impératif, quoi). Le plus compliqué a été de me retrouver au milieu des variables. Bien que les noms soient très explicites, le problème était que toutes étaient globales mais parfois écrites dans une procédure 1 et lues dans une autre, sans aucune garantie que la procédure 1 soit lue avant la 2. Alors mieux vaut des noms plus courts, moins explicites, mais en contrepartie, une portée la plus courte possible, dans ce cas la procédure qui contient la variable fait partie intégrante de son contexte et ça fait encore un commentaire en moins.

    Parfois, un commentaire comble une lacune du langage. Dans un commentaire plus haut on donne l'exemple de variables avec unité de mesure: or, si dans un langage on a la possibilité de créer des types dérivant de "int" ou de "float" de façon type-safe (c'est à dire que le type "length" ne puisse plus recevoir d'entrée de type "speed" bien que les deux dérivent de "float") alors le problème est résolu sans commentaire. J'ai utilisé cette technique en Ada une fois, redoutablement efficace car le compilateur relève toutes les erreurs de type.
    Donc, à un commentaire du genre "doit être supérieur à zéro" je préfèrerais un type non signé. Mais la plupart des langages ne le proposent pas sur les flottants.
    Le must étant alors la programmation par contrat, où on peut préciser toutes les contraintes possibles sur une variable : on le fait dans le langage lui-même, quand le langage ne le propose pas, inévitablement c'est le genre de truc qu'on retrouve dans les commentaires.

    Le langage doit aussi permettre de définir précisément qui va initialiser et modifier la variable. A ce titre je déteste cette habitude de créer de simples "beans" où chaque variable peut être modifiée par n'importe qui, le "setter" ne faisant rien de plus que permettre sa modification sans même prendre la peine de réduire l'encapsulation (99% des setters étant publics). En ce moment je me débats avec l'API d'un gros programme, très mal documenté, où le nom des "propriétés" a beau être très explicite, il ne m'indique en rien si la variable que j'utilise va bien être préalablement remplie avant que mon plugin tente d'y accéder. Comme je n'ai besoin de cette propriété qu'en lecture, je n'ai pas le contexte pour la calculer moi-même et aucun contexte ne m'indique quelle méthode appeler pour le faire. Au fond cette propriété aurait dû être une méthode, mais je ne suis pas l'auteur de l'API alors...

  10. #30
    Futur Membre du Club
    Inscrit en
    Avril 2006
    Messages
    5
    Détails du profil
    Informations forums :
    Inscription : Avril 2006
    Messages : 5
    Points : 5
    Points
    5
    Par défaut
    Je ne comprend pas le débat.

    Comme dit précédemment l'un n'empêche pas l'autre.
    Mais surtout un commentaire peut définir le "pourquoi" on fait tel code, chose que ne fera jamais le code en lui même, malgré toute la clarté que l'on peut lui apporter.

    Et pour alléger le sujet, le commentaire est en vert dans l'IDE, et moi, j'aime bien le vert.

  11. #31
    Membre émérite
    Inscrit en
    Janvier 2011
    Messages
    805
    Détails du profil
    Informations personnelles :
    Localisation : Autre

    Informations forums :
    Inscription : Janvier 2011
    Messages : 805
    Points : 2 917
    Points
    2 917
    Par défaut
    Citation Envoyé par esperanto Voir le message
    Avant de se poser la question du nom d'une variable et de la nécessité ou non de la commenter, je crois qu'il est bien plus important de définir dès le départ sa portée.
    Or j'ai fait une recherche dans l'article, le mot "scope" n’apparait que dans un ou deux commentaires, pas dans l'article lui-même.

    [...] Alors mieux vaut des noms plus courts, moins explicites, mais en contrepartie, une portée la plus courte possible, dans ce cas la procédure qui contient la variable fait partie intégrante de son contexte et ça fait encore un commentaire en moins.
    Je pense que l'article ne parle pas de scope, tout simplement parce que c'est une problématique largement décorrélée de celle du nommage et des commentaires. Pour ma part, tant qu'à faire il vaut mieux des variables bien scopées et bien nommées, l'un n'empêche pas l'autre.

    Citation Envoyé par esperanto Voir le message
    Parfois, un commentaire comble une lacune du langage. Dans un commentaire plus haut on donne l'exemple de variables avec unité de mesure: or, si dans un langage on a la possibilité de créer des types dérivant de "int" ou de "float" de façon type-safe (c'est à dire que le type "length" ne puisse plus recevoir d'entrée de type "speed" bien que les deux dérivent de "float") alors le problème est résolu sans commentaire. J'ai utilisé cette technique en Ada une fois, redoutablement efficace car le compilateur relève toutes les erreurs de type.
    +1

    Citation Envoyé par esperanto Voir le message
    Donc, à un commentaire du genre "doit être supérieur à zéro" je préfèrerais un type non signé. Mais la plupart des langages ne le proposent pas sur les flottants.
    Le must étant alors la programmation par contrat, où on peut préciser toutes les contraintes possibles sur une variable : on le fait dans le langage lui-même, quand le langage ne le propose pas, inévitablement c'est le genre de truc qu'on retrouve dans les commentaires.
    +1 mais la programmation par contrat ne passe pas forcément par une feature intégrée dans le langage, il existe des frameworks ou au pire les contrats du pauvre : des Assert() ou des checks à la main. Même sans utiliser DbC en tant que tel, c'est déjà ce que je fais systématiquement : plutôt qu'un commentaire "Attention, cet entier ne peut être négatif", je fais une vérification avec levée d'exception ou retour d'échec en cas de problème (et j'espère qu'on est nombreux à le faire). L'absence de contrats dans le langage ne doit pas être un prétexte pour faire du "contrôle par commentaires" là où il pourrait être fait au runtime.

    Citation Envoyé par esperanto Voir le message
    A ce titre je déteste cette habitude de créer de simples "beans" où chaque variable peut être modifiée par n'importe qui, le "setter" ne faisant rien de plus que permettre sa modification sans même prendre la peine de réduire l'encapsulation (99% des setters étant publics). En ce moment je me débats avec l'API d'un gros programme, très mal documenté, où le nom des "propriétés" a beau être très explicite, il ne m'indique en rien si la variable que j'utilise va bien être préalablement remplie avant que mon plugin tente d'y accéder. Comme je n'ai besoin de cette propriété qu'en lecture, je n'ai pas le contexte pour la calculer moi-même et aucun contexte ne m'indique quelle méthode appeler pour le faire. Au fond cette propriété aurait dû être une méthode, mais je ne suis pas l'auteur de l'API alors...
    Tout à fait, et un simple constructeur garantissant que la propriété est bien remplie + passer les setters en privé permet de remédier à cela. C'est évidemment supérieur à un commentaire qui dirait "cette propriété est remplie quand blablabla..."

    En résumé, typesystem (et/ou) nommage > commentaires, on est d'accord.

  12. #32
    Membre émérite
    Inscrit en
    Janvier 2011
    Messages
    805
    Détails du profil
    Informations personnelles :
    Localisation : Autre

    Informations forums :
    Inscription : Janvier 2011
    Messages : 805
    Points : 2 917
    Points
    2 917
    Par défaut
    Citation Envoyé par yahiko Voir le message
    Si on se donne la peine de lire l'article original et la refactorisation de l'auteur, il n'est pas si évident que cela que le code remanié soit si clair par rapport au code de départ.
    Remplacer une procédure, pas génialement écrite certes, mais qui est loin d'être indigeste, par l'usine à gaz qu'est sa classe avec toutes ses méthodes que l'auteur introduit dans son refactoring, juste pour séparer le nom d'un fichier de son répertoire... OMG...
    Pas d'accord. Je trouve le code refactoré beaucoup plus lisible. Si je suis simplement curieux de savoir ce que fait la méthode Split(), j'ai 4 lignes de code à lire au lieu de plus d'une dizaine. Le rapport signal/bruit est bien meilleur que dans la version originale.

    Quand je veux modifier le comportement de Split(), il se peut que les sauts nécessaires vers les sous-méthodes concernées rendent les choses plus discutables. Mais comme en général on lit beaucoup plus une base de code qu'on ne la modifie (et que pour la modifier il faut la lire)...

    Citation Envoyé par yahiko Voir le message
    Au niveau de l'argumentation assez fallacieuse, l'auteur tente de montrer que parce qu'il est possible d'écrire du code plus clair (aucun souci avec cette affirmation), alors les commentaires sont inutiles... C'est un peu comme mélanger les choux et les carottes. Avec ce genre de raisonnement on peut aussi dire que comme on peut bien commenter, il n'est pas nécessaire d'écrire du code clair. C'est absurde évidemment. Il faut à la fois écrire du code clair et bien commenter.
    A ceci près que les commentaires ont un gros défaut par rapport au code, c'est qu'ils peuvent (et vont généralement) devenir désynchronisés avec le code.

    D'où la hiérarchie nommage > commentaires quand les deux satisfont exactement le même but.

  13. #33
    Membre émérite
    Inscrit en
    Janvier 2006
    Messages
    719
    Détails du profil
    Informations forums :
    Inscription : Janvier 2006
    Messages : 719
    Points : 2 712
    Points
    2 712
    Par défaut
    Citation Envoyé par Luckyluke34 Voir le message
    Pour ma part, tant qu'à faire il vaut mieux des variables bien scopées et bien nommées, l'un n'empêche pas l'autre.
    Sauf que si la portée est très courte tu peux te contenter d'un nom court parce que celui qui tombe sur la variable a déjà lu le nom de la méthode dans laquelle elle est définie, ce nom se retrouvant quelques lignes plus haut.
    Pour prendre un autre exemple, est-il nécessaire d'utiliser des noms de classe à rallonge dès lors que ces classes sont dans un package dont le nom est déjà suffisamment explicite?
    oui si tout le monde a la sale habitude d'importer tous les packages en totalité au début du code, ce qui fait qu'on ne voit jamais le nom "complet" de la classe
    non si on travaille proprement.


    +1 mais la programmation par contrat ne passe pas forcément par une feature intégrée dans le langage, il existe des frameworks ou au pire les contrats du pauvre : des Assert() ou des checks à la main. Même sans utiliser DbC en tant que tel, c'est déjà ce que je fais systématiquement : plutôt qu'un commentaire "Attention, cet entier ne peut être négatif", je fais une vérification avec levée d'exception ou retour d'échec en cas de problème (et j'espère qu'on est nombreux à le faire). L'absence de contrats dans le langage ne doit pas être un prétexte pour faire du "contrôle par commentaires" là où il pourrait être fait au runtime.
    D'accord, mais à un détail près : le contrat fait partie intégrante de la signature d'une méthode, quand tu utilises un générateur de documentation de type "doxygen" le contrat devrait être présent, ce qui n'est ni le cas d'un commentaire à l'intérieur de la méthode, ni d'un assert.
    Parce que l'utilisateur qui appelle ma méthode avec un nombre négatif alors que c'est interdit, je veux bien lui balancer une exception mais je trouve quand même plus propre de le prévenir avant (dans la doc ou dans un contrat) plutôt que de le laisser se planter. Surtout si j'utilise un langage à typage fort.

    Et dans certains cas, un contrat peut être vérifié par le compilateur donc empêcher la compilation.

  14. #34
    Membre émérite
    Homme Profil pro
    Dev senior .Net, (ex-immigré français au Québec)
    Inscrit en
    Janvier 2006
    Messages
    727
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 51
    Localisation : France, Gironde (Aquitaine)

    Informations professionnelles :
    Activité : Dev senior .Net, (ex-immigré français au Québec)

    Informations forums :
    Inscription : Janvier 2006
    Messages : 727
    Points : 2 383
    Points
    2 383
    Par défaut
    Je suis de plus en plus pour l'idée qu'un code bien écrit doit se lire facilement (notez bien que j'invente rien,la)' Pour continuer dans l'analogie, dans un livre, on ne mets des notes en base de page que quand le lecteur ne peut pas comprendre / n'a pas les références nécessaires pour comprendre.

    Pour moi, dans l'idéal, le code c'est ainsi. On mets des commentaires soit parcequ'il y a vraiment une complexité du code extrême ou pour expliciter le fonctionnel, s'il n'est pas possible de l'exprimer autrement.

    A ce titre, je trouve ce remplacement

    Code : Sélectionner tout - Visualiser dans une fenêtre à part
    1
    2
    3
        // ignore a trailing slash
            if (length > rootLength && EndsInDirectorySeparator(validatedFullPath))
                length--;
    par
    bien vu.

    On peut critiquer la création de fonction utilisée une seule fois. D'un autre côté il m'est arrivé de reprendre du code mal écrit, et un truc qui aide vraiment a défricher des fonctions généralement trop grosse, c'est justement d'extraire des bouts de codes dans des fonctions a part bien nommées, pour ne garder que la substantifique moelle du code de la fonction (et on revient a la littérature)

    Par exemple, si les 20 premiéres lignes d'un fonction, c,est la validation d'un objet passé en paramètre, pour suivre sur 30 lignes de traitement de cet objet, je trouve qu'on gagnera pas mal a mettre la partie validation dans sa propre fonction. même si cette validation est ultra spécifique. Parcequ'usuellement, ce sur quoi on va bosser, c'est le traitement, et pas la validation.

  15. #35
    Membre actif
    Homme Profil pro
    Développeur informatique
    Inscrit en
    Juillet 2014
    Messages
    125
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 73
    Localisation : France, Aisne (Picardie)

    Informations professionnelles :
    Activité : Développeur informatique
    Secteur : Santé

    Informations forums :
    Inscription : Juillet 2014
    Messages : 125
    Points : 230
    Points
    230
    Par défaut
    je suis, bien entendu, d'accord c'est ce que je fais depuis des années, mais des noms de variables et des noms de fonctions et procédures explicites cela va aussi avec des commentaires :
    Par habitude voila comment je procède:

    une ou deux lignes expliquant la fonction de la sub plus quelques lignes dans la sub si nécessaire.
    je banni les variables courtes =I, j, Y, X ... en les remplaçant par des noms plus facile à retrouver par exemple: Jlong pour les variables génériques, Xaxe, Yaxe pour les variables dédiées.
    et comme le disait un commentateur, il faut aussi bannir les noms de variables trop long.
    et je commence mes variables string par S_ qui remplace le $ des premiers basics
    Je viens de restructurer un programme vieux de 18 ans , je ne dis pas que je n'ai pas eu de difficultés, c'est évident, mais j'ai très vite retrouvé mes petits.

    la programmation c'est d'abord du pragmatisme.

  16. #36
    Expert éminent sénior
    Avatar de Luc Hermitte
    Homme Profil pro
    Développeur informatique
    Inscrit en
    Août 2003
    Messages
    5 275
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France, Haute Garonne (Midi Pyrénées)

    Informations professionnelles :
    Activité : Développeur informatique
    Secteur : Aéronautique - Marine - Espace - Armement

    Informations forums :
    Inscription : Août 2003
    Messages : 5 275
    Points : 10 985
    Points
    10 985
    Par défaut
    Dans un monde idéal, le respect du SRP et des variables bien nommées lèvent le besoin de commentaires dans le code. Côté SRP, j'ai même vu une conf où le conférencier (Sean Parent) allait jusqu'à dire qu'une fonction ne doit jamais contenir de for/while et faire autre chose -- il préconise l'utilisation d'algorithmes génériques à la place (for_each, find_if, ...), et que s'il manque des algos il faut les écrire et les partager. Mais je me disperse (légèrement!).

    Il reste toutefois des commentaires incontournables : les en-têtes de fichiers pour contenir les informations de copyright et de licence. Et des difficilement contournables : les cartouches à la doxygen/javadoc qui vont expliquer le rôle des fonctions et des classes au delà des évidences portées par le nom : typiquement le contrat (pré-conditions, post-conditions, invariants), et éventuelles exceptions levées et sous quelles conditions. Le comment cela s'utilise peut être utile aussi (cookbook). Je soupçonne même que certains iraient jusqu'à dire que ces commentaires d'interface peuvent se remplacer par des Test Unitaires. En partie, c'est probable.

    Le vrai soucis, c'est les taux de commentaires imposées -- surtout si le calcul de la métrique ignore les commentaires d'interface. Ils poussent vite à rajouter des redondances un peu, voire excessivement, inutiles. D'autant qu'elles vont très vite devenir obsolètes au fil des refactoring (*). Le pire des cas, c'est encore quand le commentaire explique un truc, que le code fait autre chose, et qu'au final la fonction est buggué. Là, difficile de savoir si la correction consiste à corriger pour faire ce que le commentaire explique, ou s'il faut chercher une nouvelle solution. Et encore, il faut commencer par comprendre ce qui est exactement fait dans la fonction, en espérant que l'on ne se base pas sur des commentaires obsolètes pour se faire une idée.

    (*) Je ne doute pas que plusieurs d'entre-vous vont hurler en disant que le problème est là: il fallait garder les commentaires à jour. Mais soyons honnête un instant! Vous n'en voyez jamais des commentaires obsolètes ? Plus un code sur lequel j'interviens est vieux, plus la chance pour que ses commentaires soient obsolètes est importante. Et l'expérience m'a montré que la probabilité d'en voir est très loin d'être nulle. Sans parler qu'au fur et à mesure que l'on corrige un code pour lui faire passer les tests, on oublie vite de patcher les commentaires tant que la correction n'est pas validée. Avant que mes collègues se focalisent sur des commentaires, je préfère de loin qu'ils se focalisent à respecter le SRP (et d'autres aspects bien plus importants)
    Blog|FAQ C++|FAQ fclc++|FAQ Comeau|FAQ C++lite|FAQ BS|Bons livres sur le C++
    Les MP ne sont pas une hotline. Je ne réponds à aucune question technique par le biais de ce média. Et de toutes façons, ma BAL sur dvpz est pleine...

  17. #37
    Expert éminent
    Avatar de Matthieu Vergne
    Homme Profil pro
    Consultant IT, chercheur IA indépendant
    Inscrit en
    Novembre 2011
    Messages
    2 261
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France

    Informations professionnelles :
    Activité : Consultant IT, chercheur IA indépendant
    Secteur : High Tech - Éditeur de logiciels

    Informations forums :
    Inscription : Novembre 2011
    Messages : 2 261
    Points : 7 748
    Points
    7 748
    Billets dans le blog
    3
    Par défaut
    Citation Envoyé par Luc Hermitte Voir le message
    Il reste toutefois des commentaires incontournables : les en-têtes de fichiers pour contenir les informations de copyright et de licence. Et des difficilement contournables : les cartouches à la doxygen/javadoc qui vont expliquer le rôle des fonctions et des classes au delà des évidences portées par le nom : typiquement le contrat (pré-conditions, post-conditions, invariants), et éventuelles exceptions levées et sous quelles conditions. Le comment cela s'utilise peut être utile aussi (cookbook). Je soupçonne même que certains iraient jusqu'à dire que ces commentaires d'interface peuvent se remplacer par des Test Unitaires. En partie, c'est probable.
    Je pense qu'il est important de bien séparer commentaire et documentation. Les deux ont des finalités différentes et, du coup, il n'y a pas de raison à ce qu'on tombe d'accord* : les uns parleront des commentaires hors documentations, les autres de documentation, et il n'y aura jamais consensus. Si on sépare les deux, ce dont tu parles là est de la documentation, pas des commentaires. Et là dessus, je pense que tout le monde est d'accord : la documentation est nécessaire, en particulier quand tu ne travailles pas tout seul.

    * C'est comme la loi renseignement : on fait une loi pour le terrorisme, les intérêts économiques de la France, l'ordre publique, etc. et après on voit des débats houleux dans l'hémicycle où chacun prend l'exemple qui lui va pour illustrer sa position, et au final on n'avance pas.

    Citation Envoyé par Luc Hermitte Voir le message
    Le vrai soucis, c'est les taux de commentaires imposées -- surtout si le calcul de la métrique ignore les commentaires d'interface. Ils poussent vite à rajouter des redondances un peu, voire excessivement, inutiles. D'autant qu'elles vont très vite devenir obsolètes au fil des refactoring (*). Le pire des cas, c'est encore quand le commentaire explique un truc, que le code fait autre chose, et qu'au final la fonction est buggué. Là, difficile de savoir si la correction consiste à corriger pour faire ce que le commentaire explique, ou s'il faut chercher une nouvelle solution. Et encore, il faut commencer par comprendre ce qui est exactement fait dans la fonction, en espérant que l'on ne se base pas sur des commentaires obsolètes pour se faire une idée.

    (*) Je ne doute pas que plusieurs d'entre-vous vont hurler en disant que le problème est là: il fallait garder les commentaires à jour. Mais soyons honnête un instant! Vous n'en voyez jamais des commentaires obsolètes ? Plus un code sur lequel j'interviens est vieux, plus la chance pour que ses commentaires soient obsolètes est importante. Et l'expérience m'a montré que la probabilité d'en voir est très loin d'être nulle. Sans parler qu'au fur et à mesure que l'on corrige un code pour lui faire passer les tests, on oublie vite de patcher les commentaires tant que la correction n'est pas validée. Avant que mes collègues se focalisent sur des commentaires, je préfère de loin qu'ils se focalisent à respecter le SRP (et d'autres aspects bien plus importants)
    C'est davantage sur ce point que se situe le débat, principalement (pour autant que je généralise) entre une complémentarité nécessaire, le commentaire ayant autant d'utilité que le code, ou exceptionnelle, le commentaire étant un moyen de préciser ce que le code ne précise pas ou mal. Ou dit autrement, est-ce que la règle est la présence de commentaires et l'exception l'absence de commentaires, ou l'inverse.
    Site perso
    Recommandations pour débattre sainement

    Références récurrentes :
    The Cambridge Handbook of Expertise and Expert Performance
    L’Art d’avoir toujours raison (ou ce qu'il faut éviter pour pas que je vous saute à la gorge {^_^})

  18. #38
    Membre éclairé
    Homme Profil pro
    Enseignant
    Inscrit en
    Décembre 2007
    Messages
    206
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 50
    Localisation : Suisse

    Informations professionnelles :
    Activité : Enseignant
    Secteur : Enseignement

    Informations forums :
    Inscription : Décembre 2007
    Messages : 206
    Points : 849
    Points
    849
    Par défaut
    Je pense que les commentaires qui se trouvent dans le code tout comme le code lui-même sont une partie intégrante de la documentation, donc non, je ne pense pas que "des variables bien nommées valent mieux qu'un bon commentaire". Si la proposition avait été "des variables bien nommées valent mieux que des commentaires redondants par rapport au code", j'aurais certainement été d'accord car par principe ce qu'on peut dire en code, il faut le dire en code. Un bon commentaire doit apporter une information nécessaire à la compréhension du code mais que celui-ci ne fournit pas et ne peut pas fournir. Beaucoup de langages de programmation de haut niveau permettent de décrire un algorithme aussi efficacement qu'un pseudo-code ou qu'un structogramme, mais aucun ne permettent de décrire, par exemple, les raisons qui ont mené au choix de cet algorithme ou le contexte dans lequel il est utilisé. Pour cela, il y a les commentaires. Je ne vois donc aucune raison de donner plus de valeur aux identificateurs qu'aux *bons* commentaires; et même si des certains commentaires seront moins bons que d'autres, un proverbe chinois : "L'encre la plus pâle vaut mieux que la meilleure mémoire."

  19. #39
    Expert éminent
    Avatar de Matthieu Vergne
    Homme Profil pro
    Consultant IT, chercheur IA indépendant
    Inscrit en
    Novembre 2011
    Messages
    2 261
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France

    Informations professionnelles :
    Activité : Consultant IT, chercheur IA indépendant
    Secteur : High Tech - Éditeur de logiciels

    Informations forums :
    Inscription : Novembre 2011
    Messages : 2 261
    Points : 7 748
    Points
    7 748
    Billets dans le blog
    3
    Par défaut
    Citation Envoyé par ptah35 Voir le message
    et même si des certains commentaires seront moins bons que d'autres, un proverbe chinois : "L'encre la plus pâle vaut mieux que la meilleure mémoire."
    Je doute que ce proverbe soit pertinent ici, dans le sens où il compare l'écriture à la mémorisation, et non deux langages différents utilisés ensemble.
    Site perso
    Recommandations pour débattre sainement

    Références récurrentes :
    The Cambridge Handbook of Expertise and Expert Performance
    L’Art d’avoir toujours raison (ou ce qu'il faut éviter pour pas que je vous saute à la gorge {^_^})

  20. #40
    Membre éclairé
    Homme Profil pro
    Enseignant
    Inscrit en
    Décembre 2007
    Messages
    206
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 50
    Localisation : Suisse

    Informations professionnelles :
    Activité : Enseignant
    Secteur : Enseignement

    Informations forums :
    Inscription : Décembre 2007
    Messages : 206
    Points : 849
    Points
    849
    Par défaut
    Citation Envoyé par Matthieu Vergne Voir le message
    Je doute que ce proverbe soit pertinent ici, dans le sens où il compare l'écriture à la mémorisation, et non deux langages différents utilisés ensemble.
    Un commentaire devrait donner des informations que le code ne donne pas et très souvent, on omet d'écrire un commentaire car ces informations nous paraissent aller de soi. L'expérience nous montre que ce qui nous parait évident lors de l'écriture d'un code ne l'est plus du tout quelques mois plus tard. Ce que je voulais dire est précisément qu'il vaut mieux avoir des commentaires imparfaits que de devoir compter sur la mémoire des uns et des autres.

Discussions similaires

  1. Réponses: 5
    Dernier message: 19/05/2008, 19h40
  2. Affichage des variables d'un programme asm
    Par fgh39 dans le forum x86 32-bits / 64-bits
    Réponses: 2
    Dernier message: 13/05/2008, 07h16
  3. Réponses: 3
    Dernier message: 23/07/2007, 19h01
  4. Comment créer des variables nommées A1, A2, A3... An
    Par BLACKDOM dans le forum MATLAB
    Réponses: 6
    Dernier message: 16/04/2007, 18h19
  5. Réponses: 23
    Dernier message: 22/05/2006, 20h56

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