+ Répondre à la discussion Actualité déjà publiée
Page 1 sur 8 12345 ... DernièreDernière
  1. #1
    Chroniqueur Actualités
    Avatar de Michael Guilloux
    Homme Profil pro
    Consultant
    Inscrit en
    juillet 2013
    Messages
    1 646
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 27
    Localisation : Côte d'Ivoire

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

    Informations forums :
    Inscription : juillet 2013
    Messages : 1 646
    Points : 47 583
    Points
    47 583
    Billets dans le blog
    2

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

    Programmation : quand faut-il commenter son code ? Google s’invite dans le débat
    et montre que les commentaires peuvent très souvent être évités

    En apprenant la programmation, votre professeur vous a certainement dit de toujours et bien commenter votre code. Rappelons que les commentaires sont des portions du code source ignorées par le compilateur ou l’interpréteur, car ils ne sont pas nécessaires à l’exécution du programme. Ils sont généralement insérés dans le code afin qu’il soit facile à comprendre et de sorte qu’on puisse le modifier facilement à l’avenir. Mais certains en font peut-être un peu trop avec les commentaires, en essayant de les placer à chaque petit coin du code ; une pratique qui est désapprouvée par beaucoup de développeurs expérimentés.

    Pour ces derniers, si le code est tellement compliqué que cela doit être expliqué, il est presque toujours préférable d’améliorer le code que d’ajouter des commentaires. Dans un billet de blog datant de 2013, un développeur .NET du nom de Steve Smith a donc voulu trancher le débat en expliquant que « les commentaires doivent être généralement évités si le code peut dire ce qu’il fait. » Steve Smith pense en effet que « les bons commentaires disent ce que le code ne peut pas exprimer, comme pourquoi une technique particulière a été favorisée ou les dangers de l’optimisation d’un bloc de code. La plupart des autres types de commentaires sont simplement du bruit et leur présence encombre le code. »

    Malgré tous les avis sur la question, la manière d’utiliser les commentaires reste une vieille question dans les habitudes de programmation. Google s’invite aujourd’hui dans le débat et montre qu’en réalité les commentaires peuvent très souvent être évités. « En lisant un code, souvent, il n'y a rien de plus utile qu'un commentaire bien placé. Cependant, les commentaires ne sont pas toujours bons. Parfois, le besoin d'un commentaire peut être un signe que le code devrait être refactorisé. Utilisez un commentaire lorsqu'il est impossible de faire en sorte que votre code s'explique par lui-même », expliquent Dori Reuveni et Kevin Bourrillion sur Google Testing Blog.

    Si vous pensez avoir besoin d'un commentaire pour expliquer ce qu'est un code, ils proposent alors de procéder d'abord à l'une des opérations suivantes :

    1. Introduire une variable explicative
    Avec commentaire :
    Code : Sélectionner tout - Visualiser dans une fenêtre à part
    1
    2
    3
    // Subtract discount from price.
    finalPrice = (numItems * itemPrice)
        - min(5, numItems) * itemPrice * 0.1;
    Sans commentaire :
    Code : Sélectionner tout - Visualiser dans une fenêtre à part
    1
    2
    3
    4
    price = numItems * itemPrice;
    discount =
        min(5, numItems) * itemPrice * 0.1;
    finalPrice = price - discount;

    2. Extraire une méthode
    Avec commentaire :
    Code : Sélectionner tout - Visualiser dans une fenêtre à part
    1
    2
    // Filter offensive words.
    for (String word : words) { ... }
    Sans commentaire :
    Code : Sélectionner tout - Visualiser dans une fenêtre à part
    filterOffensiveWords(words);

    3. Utiliser un nom d'identificateur plus descriptif
    Avec commentaire :
    Code : Sélectionner tout - Visualiser dans une fenêtre à part
    int width = ...; // Width in pixels.
    Sans commentaire :
    Code : Sélectionner tout - Visualiser dans une fenêtre à part
    int widthInPixels = ...;

    4. Ajouter un contrôle dans le cas où votre code a des hypothèses
    Avec commentaire :
    Code : Sélectionner tout - Visualiser dans une fenêtre à part
    1
    2
    // Safe since height is always > 0.
    return width / height;
    Sans commentaire :
    Code : Sélectionner tout - Visualiser dans une fenêtre à part
    1
    2
    checkArgument(height > 0);
    return width / height;

    Il y a bien sûr des cas où un commentaire peut être utile. C'est le cas par exemple lorsqu'il est nécessaire de révéler votre intention, c'est-à-dire expliquer pourquoi le code fait quelque chose (ce qui est différent d'expliquer ce que fait le code). On peut, entre autres, également utiliser des commentaires pour apporter une clarification à une question qui a été soulevée lors de la revue du code ou que les lecteurs du code pourraient avoir. Dans tous les cas, les ingénieurs de Google pensent qu'il faut éviter les commentaires qui ne font que dire ce que fait le code, car ce n'est que du bruit. Par exemple :
    Code : Sélectionner tout - Visualiser dans une fenêtre à part
    1
    2
    3
    4
    // Get all users.
    userService.getAllUsers();
    // Check if the name is empty.
    if (name.isEmpty()) { ... }
    Source : Google Testing Blog

    Et vous ?

    Qu’en pensez-vous ?
    À quelle fréquence pensez-vous utiliser des commentaires ? Rarement, souvent, très souvent ?
    Quelles règles observez-vous pour insérer des commentaires dans votre code ?

    Voir aussi :

    Un code bien écrit a-t-il besoin des commentaires ? Quelle est la place des commentaires dans votre code ?
    Linus Torvalds fustige des développeurs du noyau Linux pour des styles de commentaires qu'il qualifie de « dégoûtants » et visuellement déséquilibrés
    Contribuez au club : Corrections, suggestions, critiques, ... : Contactez le service news et Rédigez des actualités

  2. #2
    Membre actif
    Inscrit en
    novembre 2006
    Messages
    100
    Détails du profil
    Informations forums :
    Inscription : novembre 2006
    Messages : 100
    Points : 216
    Points
    216

    Par défaut

    Et vive les CheckStyles qui imposent de mettre des commentaires sur les getters & setters (et pire les langages qui imposent d'avoir des getters & setters ) et de lister tous les paramètres et retours des méthodes :

    /**
    * Retourne l'âge du capitaine.
    * @return âge du capitaine
    **/
    public int getAgeCapitaine() {
    return ageCapitaine;
    }
    Développeur / Formateur
    Tutoriels AngularJS / Node.js sur ma chaîne Youtube : http://www.youtube.com/user/DevDuFutur

  3. #3
    Membre régulier
    Homme Profil pro
    C/C++ - python - web
    Inscrit en
    juillet 2012
    Messages
    26
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France, Isère (Rhône Alpes)

    Informations professionnelles :
    Activité : C/C++ - python - web

    Informations forums :
    Inscription : juillet 2012
    Messages : 26
    Points : 78
    Points
    78

    Par défaut Coder proprement

    G19 et G20 pages 318 et 319 de «Coder proprement» de Robert C.Martin (ISBN 978-2-7440-2583-9)
    … rien de nouveau

  4. #4
    Membre expérimenté
    Avatar de Jarodd
    Profil pro
    Inscrit en
    août 2005
    Messages
    799
    Détails du profil
    Informations personnelles :
    Localisation : France

    Informations forums :
    Inscription : août 2005
    Messages : 799
    Points : 1 534
    Points
    1 534

    Par défaut

    Ou sinon :

    https://github.com/ryanmcdermott/clean-code-javascript

    (ça ne s'applique pas qu'au js)

  5. #5
    Membre averti
    Homme Profil pro
    Développeur Web
    Inscrit en
    mai 2009
    Messages
    195
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 45
    Localisation : Belgique

    Informations professionnelles :
    Activité : Développeur Web
    Secteur : High Tech - Multimédia et Internet

    Informations forums :
    Inscription : mai 2009
    Messages : 195
    Points : 395
    Points
    395

    Par défaut

    Tout à fait d'accord.
    Les commentaires sont le plus souvent inutiles, sauf quand la personne qui va reprendre le code est un vrai débutant (quand on donne cours par exemple), où là, on n'en met jamais assez ^^
    Longue vie au javascript ^^

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

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

    Informations forums :
    Inscription : janvier 2011
    Messages : 2 319
    Points : 6 398
    Points
    6 398

    Par défaut

    Je serai mitigé pour ma part...
    J'aurai tendance à dire que mettre des commentaires partout est inutile mais à côté de cela je travaille sur du code très gros et très complexe et sans les commentaires inutiles cela devient une galère monstrueuse pour trouver rapidement ce que l'on cherche par simple méconnaissance du code concerné...
    Toujours se souvenir que la majorité des ennuis viennent de l'espace occupé entre la chaise et l'écran de l'ordinateur.

  7. #7
    Membre éclairé
    Profil pro
    Inscrit en
    décembre 2006
    Messages
    613
    Détails du profil
    Informations personnelles :
    Localisation : France

    Informations forums :
    Inscription : décembre 2006
    Messages : 613
    Points : 657
    Points
    657

    Par défaut

    Que du bon sens qui sont déjà les principes qui devraient être suivis…*Mais l'article apporte des exemples intéressants

  8. #8
    Membre régulier
    Homme Profil pro
    Étudiant
    Inscrit en
    septembre 2016
    Messages
    42
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 20
    Localisation : France, Morbihan (Bretagne)

    Informations professionnelles :
    Activité : Étudiant

    Informations forums :
    Inscription : septembre 2016
    Messages : 42
    Points : 91
    Points
    91

    Par défaut pas si inutiles que ça !

    Je classe les commentaires dans tout ce qui permet d'informer quelqu'un sur une partie du code. Si ils existent et servent à faciliter la compréhension, c'est pas pour rien ! Et ce n'est pas parce que trop en mettre peut relever d'une mauvaise pratique qu'il ne faut pas en mettre !

    Dans les solutions proposés, il y en a une que je n'apprecie guère, celle qui consiste à vérifier les arguments d'une fonction à l'intérieur de celle ci. C'est completement contextuel pour moi. Certaines fonctions, logiquement pensées font différentes choses à certains moments. Il n'est pas toujours évident d'avoir un ensemble de paramètre dans un état consistant, selon ce que fait la fonction. Mais la plupart du temps, avoir un "contrat" entre une fonction et celui qui l'appelle, fonctionne bien. Contrat établit par une bonne documentation, qui peut être doublée par un commentaire (d'apres moi)

    Excellent article sur la programmation par contrat, sur ce meme site:

    http://luc-hermitte.developpez.com/t...n-peu-theorie/

  9. #9
    Nouveau membre du Club
    Inscrit en
    novembre 2012
    Messages
    22
    Détails du profil
    Informations forums :
    Inscription : novembre 2012
    Messages : 22
    Points : 39
    Points
    39

    Par défaut

    Une référence additionnelle à celles déjà citées:

    Jeff Atwood: Code Tells You How, Comments Tell You Why

  10. #10
    Membre éprouvé
    Profil pro
    Inscrit en
    octobre 2005
    Messages
    845
    Détails du profil
    Informations personnelles :
    Âge : 37
    Localisation : France

    Informations forums :
    Inscription : octobre 2005
    Messages : 845
    Points : 1 282
    Points
    1 282

    Par défaut

    Un autre conseil : penser à son public. Mon code est souvent lu par des stagiaires. Dans ce cas, le conseil d'éviter les commentaires évident n'est pas valable : pour un débutant, rien n'est évident. Je profite des commentaires pour signaler les designs pattern, etc. Ça évite qu'ils ne saccagent l'architecture pour résoudre un ticket.

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

    Informations forums :
    Inscription : décembre 2006
    Messages : 613
    Points : 657
    Points
    657

    Par défaut

    Citation Envoyé par transgohan Voir le message
    je travaille sur du code très gros et très complexe et sans les commentaires inutiles cela devient une galère monstrueuse pour trouver rapidement ce que l'on cherche par simple méconnaissance du code concerné...
    Peut-être justement parce qu'il est maintenu dans un état "complexe"… D'expérience, ce type de remarque concerne toujours du code où on ne comprends rien aux noms des variables, où tout est écrit de manière procédurale et la compréhension nécessite de lire chaque ligne. Le bon sens présenté ici est de remettre en évidence que fonctions et variables ont des noms et que du code peut être déporté dans une fonction pour en expliquer l'intention.

  12. #12
    Expert éminent

    Profil pro
    tutu
    Inscrit en
    juin 2003
    Messages
    5 594
    Détails du profil
    Informations personnelles :
    Âge : 35
    Localisation : France, Paris (Île de France)

    Informations professionnelles :
    Activité : tutu

    Informations forums :
    Inscription : juin 2003
    Messages : 5 594
    Points : 9 690
    Points
    9 690
    Billets dans le blog
    3

    Par défaut

    Les commentaires qui expliquent ce que font le code sont rarement une bonne chose. Mais sur du code complexe ou ancien (qui a été réécrit / optimisé / débogué plusieurs fois), ils sont très utiles pour clarifier le contexte ou l'historique du code,
    en particulier expliquer ce que le code ne fait pas et pourquoi c'est ainsi.

    Jetez juste un oeil au source de Linux ou Chromium pour vous convaincre.

  13. #13
    Membre éclairé
    Profil pro
    Inscrit en
    décembre 2006
    Messages
    613
    Détails du profil
    Informations personnelles :
    Localisation : France

    Informations forums :
    Inscription : décembre 2006
    Messages : 613
    Points : 657
    Points
    657

    Par défaut

    Citation Envoyé par BugFactory Voir le message
    Un autre conseil : penser à son public. Mon code est souvent lu par des stagiaires. Dans ce cas, le conseil d'éviter les commentaires évident n'est pas valable : pour un débutant, rien n'est évident. Je profite des commentaires pour signaler les designs pattern, etc. Ça évite qu'ils ne saccagent l'architecture pour résoudre un ticket.
    Si il y a saccage d'une architecture du fait d'un ticket, j'appelle ça une erreur de staffing…

  14. #14
    Membre émérite
    Profil pro
    Développeur
    Inscrit en
    mars 2012
    Messages
    1 451
    Détails du profil
    Informations personnelles :
    Localisation : Belgique

    Informations professionnelles :
    Activité : Développeur
    Secteur : Communication - Médias

    Informations forums :
    Inscription : mars 2012
    Messages : 1 451
    Points : 2 396
    Points
    2 396

    Par défaut

    Les commentaires ça sert à rien, c'est pas compilé (troll off)
    Si la réponse vous a aidé, pensez à cliquer sur +1

  15. #15
    Membre averti
    Profil pro
    Inscrit en
    juin 2006
    Messages
    157
    Détails du profil
    Informations personnelles :
    Localisation : France

    Informations forums :
    Inscription : juin 2006
    Messages : 157
    Points : 311
    Points
    311

    Par défaut

    Citation Envoyé par palnap Voir le message
    Et vive les CheckStyles qui imposent de mettre des commentaires sur les getters & setters (et pire les langages qui imposent d'avoir des getters & setters ) et de lister tous les paramètres et retours des méthodes :

    /**
    * Retourne l'âge du capitaine.
    * @return âge du capitaine
    **/
    public int getAgeCapitaine() {
    return ageCapitaine;
    }
    /**
    * Retourne l'âge du capitaine.
    * @return âge du capitaine, en années ? en secondes ? en millisecondes ? peut être négatif ? peut être 0 ? sur une application multi-threadée la méthode est synchronisée ?
    **/

    Et pour le setter, @param ageCapitaine l'age du capitaine c'est de la paraphrase idiote, mais... il se passe quoi si tu mets un âge négatif ? une exception ? osef ça passe ? négatif est ramené à 0 ?

    Si tu commences par répondre à toutes ces question (et c'est le strict minimum), tu verras que les commentaires de méthode sont indispensables dès que ton projet a une taille conséquente.

    ... et bien sûr qu'il faut avoir des getters setters ! Comment tu fais quand t'as un bug et que tu veux mettre un point d'arrêt parce que la valeur que tu as dans ton objet est déconnante ? tu mets des sysout partout (quand t'as accès aux sources en modif....) ?

  16. #16
    Membre habitué
    Profil pro
    Inscrit en
    septembre 2007
    Messages
    105
    Détails du profil
    Informations personnelles :
    Âge : 49
    Localisation : Suisse

    Informations forums :
    Inscription : septembre 2007
    Messages : 105
    Points : 144
    Points
    144

    Par défaut

    Bonjour,

    Pour ma part je fait beaucoup de bruit ^^.

    Il peut y avoir des commentaires inutiles, mais la plus part du temps ce n'est pas le cas.
    En fait j'utilise les fonctions de certains scripts de création d'aide en ligne à l'aide de commentaires.
    Du coup, je décrit de manière intelligible ce que fait tel ou tel fonction, les paramètres, les entrée, les sortie, etc.

    Par contre à l'intérieur du code, il y a très peu de commentaires, seul les cas particuliers sont expliqués ou les manières d'utiliser tel ou tel API, lorsque j'ai croché pour l'implémentation.

    La seule exception, c'est lorsque la fonction (souvent Main) est divisée en plusieurs étapes, alors je les nommes avec des commentaires, qui sont souvent suivies par un appel de fonction quasi identique.

    C'est plus par flemme que ces commentaires restent présent, car j'ai de plus en plus tendance à écrire en premier les commentaires et créant ainsi une sorte de squelette que je complète par la suite avec du code.

    Le publique visé, c'est en règle général, moi ...
    Et cela me permet fréquemment de reprendre un bout de code rapidement sans me torture la tête avec le contenu du code ...

    Par contre, quand je me rend compte qu'un code est excessivement réutilisé, je me force à en faire une bibliothèque, puis à mettre à jour mes programmes où j'utilisais ce code.

    Après, c'est comme pour beaucoup de chose, les goûts et les couleurs c'est perso.
    Avec la nuance suivante, si le code doit être relu par soit-même ou par autrui, il faut faire en sorte que cela soit possible.
    Que se soit avec des commentaires, du code explicite ou les deux.

    Et ne pas oublier d'essayer de s’améliorer avec le temps (comme les bons vins). ^^

    Salutations.

  17. #17
    Rédacteur/Modérateur

    Homme Profil pro
    Network game programmer
    Inscrit en
    juin 2010
    Messages
    4 723
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 30
    Localisation : Royaume-Uni

    Informations professionnelles :
    Activité : Network game programmer

    Informations forums :
    Inscription : juin 2010
    Messages : 4 723
    Points : 19 493
    Points
    19 493

    Par défaut

    Citation Envoyé par Washmid Voir le message
    /**
    * Retourne l'âge du capitaine.
    * @return âge du capitaine, en années ? en secondes ? en millisecondes ? peut être négatif ? peut être 0 ? sur une application multi-threadée la méthode est synchronisée ?
    **/

    Et pour le setter, @param ageCapitaine l'age du capitaine c'est de la paraphrase idiote, mais... il se passe quoi si tu mets un âge négatif ? une exception ? osef ça passe ? négatif est ramené à 0 ?

    Si tu commences par répondre à toutes ces question (et c'est le strict minimum), tu verras que les commentaires de méthode sont indispensables dès que ton projet a une taille conséquente.

    ... et bien sûr qu'il faut avoir des getters setters ! Comment tu fais quand t'as un bug et que tu veux mettre un point d'arrêt parce que la valeur que tu as dans ton objet est déconnante ? tu mets des sysout partout (quand t'as accès aux sources en modif....) ?
    Ton commentaire de méthode si indispensable devient immédiatement obsolète dans ce cas avec de bonnes pratiques
    - Pour lever l'ambiguité négatif ou pas : tu utilises un type non signé
    - Pour lever l'ambiguité de l'unité : tu utilises un type plus spécifique comme disons Age

    Si tu as une méthode process, check, qui fait vraiment des opérations, tu peux vouloir détailler ce qu'il se passe quand tu l'appelles, ce que ça implique.
    Un simple getter ou setter, le commenter c'est au mieux stupide, cf ci-dessus.
    Pensez à consulter la FAQ ou les cours et tutoriels de la section C++.
    Un peu de programmation réseau ?
    Aucune aide via MP ne sera dispensée. Merci d'utiliser les forums prévus à cet effet.

  18. #18
    Membre éclairé
    Profil pro
    Inscrit en
    décembre 2006
    Messages
    613
    Détails du profil
    Informations personnelles :
    Localisation : France

    Informations forums :
    Inscription : décembre 2006
    Messages : 613
    Points : 657
    Points
    657

    Par défaut

    Citation Envoyé par palnap Voir le message
    Et vive les CheckStyles qui imposent de mettre des commentaires sur les getters & setters (et pire les langages qui imposent d'avoir des getters & setters ) et de lister tous les paramètres et retours des méthodes :

    /**
    * Retourne l'âge du capitaine.
    * @return âge du capitaine
    **/
    public int getAgeCapitaine() {
    return ageCapitaine;
    }
    Sauf que ce n'est pas des commentaires mais de la documentation…

    Citation Envoyé par Washmid Voir le message
    Et pour le setter, @param ageCapitaine l'age du capitaine c'est de la paraphrase idiote, mais... il se passe quoi si tu mets un âge négatif ? une exception ? osef ça passe ? négatif est ramené à 0 ?
    Si on parle CheckStyle et getters/setters, on parle d'un langage tel que Java, donc la levée d'exception est déclarée. Et si une méthode "setAge" ne lève pas une exception pour un âge négatif ou se permet de la ramener à 0, c'est plutôt un signe qu'il faut réécrire une classe Capitaine fiable…

    Et si je veux aller plus loin, je dirai que si il s'agit réellement de Java, il ne se passe rien, le paramètre si du bon type est accepté et c'est tout. La validation passe par des validateurs, classes dédiées incorporés aux CapitaineFactory…

    Si tu commences par répondre à toutes ces question (et c'est le strict minimum), tu verras que les commentaires de méthode sont indispensables dès que ton projet a une taille conséquente.
    Même sans qu'il ai une taille conséquente… Les méthodes, fonctions et paramètres doivent être documentés au minimum pour expliquer les limites des paramètres comme tu l'a écris.

    ... et bien sûr qu'il faut avoir des getters setters ! Comment tu fais quand t'as un bug et que tu veux mettre un point d'arrêt parce que la valeur que tu as dans ton objet est déconnante ? tu mets des sysout partout (quand t'as accès aux sources en modif....) ?
    Tout dépend si tu écrit un code pour être mis en production ou pour être débuggué… Fondamentalement, un "setAge" du capitaine n'a aucun sens. Il suppose entre autre qu'avant d'appeler setAge, un objet de type Capitaine a été créé avec un paramètre age à Null… C'est normal ? Et quelle est la visibilité de setAge ? Publique, privée ? Si elle est publique, on est bien d'accord que ton objet Capitaine peut changer d'âge à mon bon vouloir dans mon programme ? Enfin, l'année prochaine, j'ai quoi, un capitaine qui a le même âge ou c'est à moi d'incrémenter la valeur ?
    La présence des getters/setters a un grand intérêt : elle permet de déterminer qu'un code "orienté objet" a été écrit par des développeurs qui n'ont aucune notion de POO.

  19. #19
    Membre expert Avatar de jopopmk
    Homme Profil pro
    Développeur informatique
    Inscrit en
    mars 2011
    Messages
    1 830
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France

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

    Informations forums :
    Inscription : mars 2011
    Messages : 1 830
    Points : 3 427
    Points
    3 427

    Par défaut

    Faisons rapide et simple :

    1. Introduire une variable explicative
    Non, je vais pas rajouter une variable inutile.
    Si vraiment on a besoin d'une explication alors un commentaire va très bien.

    2. Extraire une méthode
    Toujours non, je vais pas empiler des appels inutiles.
    Si vraiment on a besoin d'une explication alors un commentaire va très bien.

    3. Utiliser un nom d'identificateur plus descriptif
    Là c'est assez évident. Maintenant il peut arriver qu'on se retrouve avec des noms sans fin, on peut alors contextualiser les variables avec un petit commentaire (dans l'exemple, en tête d'algo, indiquer "all sizes in pixels" ).

    4. Ajouter un contrôle dans le cas où votre code a des hypothèses
    Gné ? Faire du défensif pour économiser un commentaire ? Là je sais même pas quoi dire ...

    Citation Envoyé par Michael Guilloux Voir le message
    À quelle fréquence pensez-vous utiliser des commentaires ? Rarement, souvent, très souvent ?
    Quelles règles observez-vous pour insérer des commentaires dans votre code ?
    Dans mon cas :
    - plus ou moins tout ce qui se trouve dans les headers (fonctions, globales, structs, enums), c'est ce que les dev voient de mes bilbi, ça remplace la doc
    - coté code, certains algo un peu long ont des commentaires pour comprendre facilement le keskekoi -et également se repérer, certaines fonctions en C pouvant être trèèèèès longues. Il m'arrive également parfois de pondre un algo en commençant par écrire les commentaires, mais c'est très rares qu'ils restent tels quels.

    Bon après-m' à tous
    Plus je connais de langages, plus j'aime le C.

  20. #20
    Membre éclairé
    Profil pro
    Inscrit en
    décembre 2006
    Messages
    613
    Détails du profil
    Informations personnelles :
    Localisation : France

    Informations forums :
    Inscription : décembre 2006
    Messages : 613
    Points : 657
    Points
    657

    Par défaut

    Citation Envoyé par aepli Voir le message
    Bonjour,
    En fait j'utilise les fonctions de certains scripts de création d'aide en ligne à l'aide de commentaires.
    Du coup, je décrit de manière intelligible ce que fait tel ou tel fonction, les paramètres, les entrée, les sortie, etc.
    Ce n'est pas du commentaire mais de la documentation

    La seule exception, c'est lorsque la fonction (souvent Main) est divisée en plusieurs étapes, alors je les nommes avec des commentaires, qui sont souvent suivies par un appel de fonction quasi identique.
    Donc c'est du bruit inutile.

    Après, c'est comme pour beaucoup de chose, les goûts et les couleurs c'est perso.
    C'est ce dont veulent se convaincre ceux qui ne se soucient pas de la qualité de leur code. Dans le cas particulier des commentaires, que ce soit perso ou non, un commentaire est du bruit, le bruit ne sert qu'à gêner quelqu'un et ici celui qui relis le code. Un commentaire est censé être un signal "attention, le code suivant ne parle pas de lui même". Quand c'est le cas, on perd du temps à chercher qu'est ce qu'on n'a pas compris dans le commentaire. Toutes les études sur le sujet ont montré ce type de comportement.

    Citation Envoyé par Bousk Voir le message
    1 - Pour lever l'ambiguité négatif ou pas : tu utilises un type non signé
    2 - Pour lever l'ambiguité de l'unité : tu utilises un type plus spécifique comme disons Age
    Pas tout à fait d'accord :
    1 - les types non signés n'existent pas dans tous les langages, mais de toutes manières, ils ne borneront que la valeur minimum. Un capitaine de 800 ans a-t-il un sens en supposant qu'il ne peut être un Jedi ? Un capitaine de 5 ans ?
    2 - est-il réellement besoin de créer un type pour représenter un entier ??? Surtout que dans ce cas précis, la valeur l'âge est lié au métier (ex: agences de voyage)

    De toutes manières, ces réponses sortaient de la notion de commentaire pour aborder celui de la documentation, une documentation qui ne décrit pas les paramètres montre juste que la lib est à jeter.

Discussions similaires

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

Partager

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