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. #21
    ILP
    ILP est déconnecté
    Membre confirmé
    Avatar de ILP
    Homme Profil pro
    Analyste programmeur
    Inscrit en
    Mai 2002
    Messages
    258
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 38
    Localisation : France, Finistère (Bretagne)

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

    Informations forums :
    Inscription : Mai 2002
    Messages : 258
    Points : 607
    Points
    607
    Par défaut
    Il est des fois nécessaire d'écrire du code un peu complexe. Calculs mathématique, utilisation d'API obscures, rappel pour du code à ajouter ou à améliorer. De plus on n'a pas tous le même cerveau (heureusement ), on ne pense pas tous pareil.
    Je ne sais pas trop pour les autres langages, mais en Delphi j'utilisais assez la balise { TODO 1 -uILP -cBase de données: Connexion à revoir } pour me souvenir d'un jour à l'autre, où j'en suis arrivé. Tout est alors rassemblé dans la fenêtre "À faire".
    Personnellement, j'ai tendance à trop commenter. Une action, un commentaire. Mais j'ai toujours trouvé que c'était plus facile pour me retrouver dans mon propre code .
    Et ceci en plus de nommer mes méthodes et variables de façon clair.

  2. #22
    Modérateur
    Avatar de nouknouk
    Homme Profil pro
    Inscrit en
    Décembre 2006
    Messages
    1 655
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 43
    Localisation : France

    Informations forums :
    Inscription : Décembre 2006
    Messages : 1 655
    Points : 2 161
    Points
    2 161
    Par défaut
    Si j'ai bien compris, le bonhomme nous explique qu'un commentaire non pertinent n'est pas pertinent, et qu'un commentaire pertinent est pertinent.

    Sans commentaire.
    Mon projet du moment: BounceBox, un jeu multijoueurs sur Freebox, sur PC et depuis peu sur smartphone/tablette Android.

  3. #23
    Membre confirmé

    Homme Profil pro
    Mâle reproducteur chez Amazon
    Inscrit en
    Mars 2006
    Messages
    207
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France, Paris (Île de France)

    Informations professionnelles :
    Activité : Mâle reproducteur chez Amazon

    Informations forums :
    Inscription : Mars 2006
    Messages : 207
    Points : 490
    Points
    490
    Par défaut
    Les commentaires, c'est comme l'éclairage sur l'autoroute. Ce n'est pas indispensable, mais ça aide.
    Pour vivre heureux, vivons cachés. Proverbe alien.

  4. #24
    Membre éprouvé
    Homme Profil pro
    Ingénieur développement logiciels
    Inscrit en
    Janvier 2007
    Messages
    697
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 36
    Localisation : France, Calvados (Basse Normandie)

    Informations professionnelles :
    Activité : Ingénieur développement logiciels
    Secteur : High Tech - Produits et services télécom et Internet

    Informations forums :
    Inscription : Janvier 2007
    Messages : 697
    Points : 1 241
    Points
    1 241
    Par défaut
    Citation Envoyé par nouknouk Voir le message
    Si j'ai bien compris, le bonhomme nous explique qu'un commentaire non pertinent n'est pas pertinent, et qu'un commentaire pertinent est pertinent.
    Sans commentaire.
    Je pense plutôt que le "bonhomme" cherche à montrer que tout les commentaires ne sont pas pertinents. Accessoirement il montre quels commentaires sont pertinents et lesquels ne le sont pas.
    Quand je vois les codes/commentaires sur lesquels je tombe, j'ai envie de lui dire merci !
    Bon, de mon coté j'ai tendance à ne commenter à l'intérieur des méthodes que quand la situation l’exige (algo complexe). Je ne commente les méthodes/classes seulement si elles ont vocation à être utilisées en tant qu'API ou éventuellement en attendant de trouver un nom/découpage clair (avec un TODO). Je ne vais pas perdre mon temps à ajouter des @param et autres, quand la seule lecture du nom du paramètre/méthode suffit.

  5. #25
    Nouveau membre du Club
    Profil pro
    Inscrit en
    Novembre 2005
    Messages
    13
    Détails du profil
    Informations personnelles :
    Localisation : France

    Informations forums :
    Inscription : Novembre 2005
    Messages : 13
    Points : 27
    Points
    27
    Par défaut
    Je suis de plus en plus pour un code sans commentaires. Ceux ci n'ont aucune valeur pour le compilateur, et du coup sont potentiellement erronés.

    Je ne compte plus les commentaires effacés dans le code sur lequel je travaille, parce qu'ils deviennent tous obsolètes trop vite, ou bien simplement incompréhensibles, ... et pire encore, ils nous induisent souvent en erreur après un certain temps.

  6. #26
    Membre à l'essai
    Profil pro
    Inscrit en
    Juillet 2007
    Messages
    14
    Détails du profil
    Informations personnelles :
    Localisation : France

    Informations forums :
    Inscription : Juillet 2007
    Messages : 14
    Points : 22
    Points
    22
    Par défaut
    Je ne suis pas du tout d'accord.

    Premièrement (et ça a déjà été dit), les commentaires aident quelqu'un qui reprendrait le code à le comprendre plus facilement. A part dans un HelloWorld, les noms de variables et de méthodes ne peuvent pas être assez explicites pour se passer de commentaires. Donc, au minimum, les déclarations de variables et les entêtes de méthodes doivent être commentées.

    Ensuite, concernant le commentaire dans le corps des fonctions, ils aident autant celui qui écrit le code que celui qui le reprendra un jour. C'est vrai surtout s'il s'agit d'algorithme un peu compliqué. Avant d'écrire un code compliqué, je réfléchi à l'algo, et j'écris les principales étapes de l'algo sous forme de commentaire dans le corps de ma méthode. Une fois que c'est fait, je n'ai plus besoin de réfléchir: il ne reste qu'à remplir le code entre les commentaires.

    J'ai donc un raisonnement inverse à celui de cet article: pour moi, une méthode bien commentée doit pouvoir se comprendre en lisant uniquement les commentaires; on ne comprendra pas comment le code fait, mais on saura parfaitement ce qu'il fait.

  7. #27
    Membre régulier
    Homme Profil pro
    Développeur Java
    Inscrit en
    Mars 2010
    Messages
    42
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 53
    Localisation : France, Bouches du Rhône (Provence Alpes Côte d'Azur)

    Informations professionnelles :
    Activité : Développeur Java

    Informations forums :
    Inscription : Mars 2010
    Messages : 42
    Points : 111
    Points
    111
    Par défaut les commentaires pour le pourquoi.
    Je suis d'accord avec l'article dans le sens qu'un commentaire n'est pas une paraphrase du code( cf la partie extrait(), load() etc ..)
    Par contre, en relisant du code, combien ai-je pu râler ou perdu de temps à comprendre le POURQUOI et non le COMMENT.
    J'aurais préféré dans le code parfois un commentaire qui explique un choix d'un algorithme ou d'une implémentation comme, par exemple en java, une ArrayList au lieu d'une LinkedList ( et y'en a d'autre; cet exemple n'est pas à prendre au pied de la lettre)
    J'ai pu constater aussi qu'en absence d'explication sur le pourquoi, on se retrouve avec du code dit "historique" avec lequel personne ne veux prendre de décision. Parfois aussi ne comprenant pas les raisons à l'époque de l'implémentation, on casse un code qui fonctionne pour des raisons bien particulières.
    Un commentaire devrait aussi indiquer des numéro de bug pour des fix.
    En conclusion, des commentaires, oui, mais qui explique le pourquoi. Encore faut il que le développeur joue le jeu : l'information n'est elle pas une source de pouvoir ?

  8. #28
    Invité
    Invité(e)
    Par défaut
    Trop simple.
    1. Commente-t-on uniquement un code parce qu'on pense qu'il faut "toujours" commenter un code ?

    Commente-t-on un code pour pouvoir le relire ou pour permettre aux autres de le relire ? Et la question corolaire :
    Supprime-t-on les commentaires d'un code pour le protéger contre la relecture par des yeux indélicats ?
    Quid des obfuscateurs ?
    Quid des noms de variables "auto-documentées" qui occupent 40 caractères à force de leur ajouter des préfixes et des suffixes alors que ladite variable s'appelle déjà "RésultatBoucleAprèsSuppressionDesDoublons"
    Pourquoi utilise-t-on des acronymes comme EOF, CRLF, ASCII ? Doit-on se limiter aux acronymes historiques ou peut-on en créer de nouveaux en fonction des notions manipulées par le programme et dans ce cas, où peut-on documenter ces nouveaux acronymes ?

    autres considérations :
    Dois-je commenter du javascript ? Doisje mettre des noms de variables explicites en javascript ?
    Pire :
    Quand je fais un portage entre du php et du C# , dois-je modifier les noms de variables puisque l'un est précompilé et l'autre non ?

    Difficile alors de donner une opinion expéditive sur cette question. Un beau code est à la fois facile à lire et légèrement commenté il me semble. Pour l'éducation, les commentaires mettront l'accent sur les points étudiés.
    En production dans une grande équipe , on commente pour des professionnels supposés formés.. En solitaire free-lance on évite de produire un code trop facile à lire car on craint qu'un développeur peu expérimenté jouissant de tous les droits chez le client vienne modifier le code et y introduire des bugs de débutant aussi ....

    Tout cela me fait penser que les situations peuvent être très différentes et que les personnes qui lisent votre code ne sont pas nécéssairement bien inspirées à l'égard de votre travail . Bien entendu, le contraire est non seulement possible mais hautement souhaitable et un développeur trop parano risque de s'attirer des remarques désobligeantes qui justifieront sa future parano et ainsi de suite..

    Ensuite , il y a ces languages très optimisables comme le C où on peut recourir à des syntaxes absolument illisibles pour des raisons de performance (liste chainée de pointeurs sur pointeurs sur fonctions...)

    Est ce que cette page est uniquement réservée à des étudiants ou des gens qui ne jurent que par le code ouvert ?

    Finalement , si vous etes en confiance et que les gens qui vous entourent méritent cette confiance , commentez régulièrement car , on peut parcourir le code uniquement en lisant les commentaires pour s'arréter exactement là où on a une modif à faire - modif qui sera datée et signée dans un commentaire ...

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

    Informations forums :
    Inscription : Décembre 2007
    Messages : 6 803
    Points : 32 056
    Points
    32 056
    Par défaut
    Citation Envoyé par barmic Voir le message
    (.../...)
    Le code répond à la question : « Comment ? »
    Les commentaires répondes à la question : « Pourquoi ? »
    +1

    Citation Envoyé par jiber2fr Voir le message
    (.../...)
    J'ai donc un raisonnement inverse à celui de cet article: pour moi, une méthode bien commentée doit pouvoir se comprendre en lisant uniquement les commentaires; on ne comprendra pas comment le code fait, mais on saura parfaitement ce qu'il fait.
    En fait, les deux. Je suis sans doute extrémiste, mais à mon sens, on doit pouvoir comprendre ce que fait le code en lisant le code seul(histoire de pouvoir le maintenir facilement), et on doit pouvoir comprendre ce que fait le code - et pourquoi - en ne lisant que les commentaires.

    Encore une fois, si je dois "créer un processus de paiement par TIP si l'indicateur de type de paiement est à TIP et que le montant est inférieur à 1 million d'euros, parcequ'àprès, le montant, n'entre plus dans les cases préimprimées", alors un nom de variable/méthode/procédure qui me dira tout ça sera illisible tellement il sera long

    Code : Sélectionner tout - Visualiser dans une fenêtre à part
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    'Émission de l'avis de paiement, en fonction du type de paiement : 
    'Un TIP ne peut pas dépasser 1M d'euros en raison de la taille du pré-imprimé
    Sub EmissionAvisPaiement(Client, Montant)
        Select Case True
            Case Client.PaiementPrefere = TypePaiement.Virement
                Call EmisionVirement(Client, Montant)
            Case (Client.PaiementPrefere = TypePaiement.TIP) and (Montant < 1000000)
                Call EmissionTIP(Client, Montant)
            Case Else
                Call EmissionCheque(Client, Montant)
        End Select
    End Sub
    J'ose prétendre qu'on peux comprendre ce que fait mon code en le lisant. Pour autant, il faut quand même se farcir quelques lignes. Ma première ligne de commentaire résume tout ça. La deuxième, elle donne une précision sur le pourquoi. En effet, cette règle du million n'est pas évidente. Si quelqu'un arrive après, il saura ainsi pourquoi on fait ça(le reste est à peu près évident, j'espère).
    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. #30
    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 : 37
    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 080
    Points
    8 080
    Par défaut
    Citation Envoyé par el_slapper Voir le message
    J'ose prétendre qu'on peux comprendre ce que fait mon code en le lisant. Pour autant, il faut quand même se farcir quelques lignes. Ma première ligne de commentaire résume tout ça. La deuxième, elle donne une précision sur le pourquoi. En effet, cette règle du million n'est pas évidente. Si quelqu'un arrive après, il saura ainsi pourquoi on fait ça(le reste est à peu près évident, j'espère).
    Pour moi ton commentaire n'a pas sa place dans le code, sa place est dans des spécifications fonctionnelles... Le mettre dans le code signifie qu'uniquement le développeur aura connaissance de ca, pas le MOA. Pire que ca, ta règle a de grandes chances d'être en triplon (oui je viens de créer ca) (code + commentaire + specs) et ca augmente encore plus le potentiel de désynchronisation entre les trois.

    Un code correctement construit et nommé accompagné d'une doc (mais pas dans le code) fonctionnelle, ca c'est utile, car même un non codeur peut reprendre la doc !

    PS chipotage: en plus ton code il marche pas, car même avec un montant supérieur à 1M on tombe dans le else qui envoie un TIP

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

    Informations forums :
    Inscription : Décembre 2007
    Messages : 6 803
    Points : 32 056
    Points
    32 056
    Par défaut
    Citation Envoyé par Nathanael Marchand Voir le message
    Pour moi ton commentaire n'a pas sa place dans le code, sa place est dans des spécifications fonctionnelles... Le mettre dans le code signifie qu'uniquement le développeur aura connaissance de ca, pas le MOA. Pire que ca, ta règle a de grandes chances d'être en triplon (oui je viens de créer ca) (code + commentaire + specs) et ca augmente encore plus le potentiel de désynchronisation entre les trois.
    Ben, la première année, tu as raison. Quand j'ai récupéré ce code - non commenté - il avait 36 ans d'âge. Les gens qui avaient écrit la spec étaient morts, ceux qui avaient écrit le code était à la retraite depuis deux décennies, et la doc, eh bien personne ne savait à quoi elle avait bien pu ressembler à l'époque. Il a fallu plusieurs semaines(pas à plein temps) aux MOA pour remonter jusqu'à l'origine de cette verrue.

    Avec les années, les rachats, les réorganisations, les déménagements, le source, c'est tout ce qui reste. Donc il est essentiel de mettre le pourquoi dans le code.

    Évidemment, quand on créée le code, au départ, lors du projet initial, ça parait con. Mais pour celui qui passe après, non pas celui-là, l'autre, bien longtemps après, c'est vraiment utile.

    Citation Envoyé par Nathanael Marchand Voir le message
    Un code correctement construit et nommé accompagné d'une doc (mais pas dans le code) fonctionnelle, ca c'est utile, car même un non codeur peut reprendre la doc !
    Et il en fait quoi? Soit c'est une spec fonctionelle, et c'est aux gens des métiers de le faire vivre, soit c'est un code, et c'est à nous développeurs.

    Citation Envoyé par Nathanael Marchand Voir le message
    PS chipotage: en plus ton code il marche pas, car même avec un montant supérieur à 1M on tombe dans le else qui envoie un TIP
    Corrigé.
    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.

  12. #32
    Inactif  


    Homme Profil pro
    Doctorant sécurité informatique — Diplômé master Droit/Économie/Gestion
    Inscrit en
    Décembre 2011
    Messages
    9 012
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 30
    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 012
    Points : 23 209
    Points
    23 209
    Par défaut
    Bonjour,

    Personnellement, pour moi un code est bien écrit s'il a des commentaires mais je ne met pas des commentaires à chaque lignes non plus.

    J'essaye surtout de commenter tout ce qui se trouve dans les header (méthodes, fonctions, attributs, enum, ...) ce qui me permet d'expliquer les tenants et les aboutissants des méthodes, de rajouter des notes et des warnings afin qu'on puisse tout réutiliser sans nécessairement se replonger dans le code.

    De plus, cela me permet de générer une documentation doxygen qui est aussi très pratique pour réutiliser le code sans le relire.

    Ensuite, se fier uniquement à des noms explicite est ridicule.
    Il y a toujours des personnes qui penseront autrement que nous et qui utiliseront mal notre méthode s'ils ne lisent pas la documentation, donner des noms de fonctions à rallonge ne corrigera pas totalement ce problème.

    Les noms explicites doivent aider à la compréhension du code mais seuls, ils ne peuvent pas nous dire exactement comment utiliser le code.
    Un bon code est un code dans lequel on a plus à se replonger dedans et à comprendre exactement comment il fait pour pouvoir l'utiliser.

    Ensuite dans les fichiers sources je ne met que très rarement des commentaires, le code étant assez souvent assez explicite pour qui veut le relire ( et la documentation aidant aussi à la compréhension ) mais lorsque je le juge nécessaire, je peux rajouter des commentaires, après tout cela ne coûte rien (à part le temps pour l'écrire) et c'est tout bénéfice

  13. #33
    Membre actif
    Homme Profil pro
    Développeur Web
    Inscrit en
    Mars 2011
    Messages
    154
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France, Ariège (Midi Pyrénées)

    Informations professionnelles :
    Activité : Développeur Web

    Informations forums :
    Inscription : Mars 2011
    Messages : 154
    Points : 282
    Points
    282
    Par défaut théorie/pratique
    Dans l'absolu (vers lequel on doit se diriger), je suis super d'accord avec ce mec, il ne devrai jamais y avoir de commentaire. Si l'espace de nom, la classe, la signature de la méthode et l'organisation du code sont corrects, nul besoin de commentaire, le code parle de lui-même y compris à un débutant.
    Dans la vraie vie, il en va différemment, car il arrive toujours un moment où le choix d'un nom n'est pas évident (et on a pas le temps de trouver un truc nickel), où pour aller plus vite on écrit un algo difficile à déchiffrer, des lignes trop longues, et des paramètres équivoques ou polyvalents. Dans ces cas là, les commentaires sont nécessaires. A fortiori si il s'agit d'interfaces, ou de méthodes publiques.
    Notez que le "pourquoi" d'un code peu également être explicité par son fichier de test unitaire (encore un argument qui confirme que le TDD est une bonne pratique).

  14. #34
    Membre chevronné Avatar de Jbx 2.0b
    Homme Profil pro
    Développeur C++/3D
    Inscrit en
    Septembre 2002
    Messages
    476
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 42
    Localisation : France, Loire Atlantique (Pays de la Loire)

    Informations professionnelles :
    Activité : Développeur C++/3D
    Secteur : High Tech - Éditeur de logiciels

    Informations forums :
    Inscription : Septembre 2002
    Messages : 476
    Points : 1 889
    Points
    1 889
    Par défaut
    Parfois, lorsqu'on met au point un algo compliqué, et qu'on utilise des moyens contre-nature pour l'optimiser, il faut le commenter et si possible dans les moindres détails. L'inverse s'est se tirer une balle dans le pied.
    Personnellement, j'abonde mon code de commentaires. C'est tellement rapide de taper une ligne pour expliquer ce qu'on fait... et tellement de temps gagné quand il faudra venir le modifier. Je bosse en R&D, alors le code jetable je connais !

    En fait les commentaires, c'est un peu ce qui permet de bosser de manière inconsciente, sans devoir réfléchir à décortiquer le code. C'est l'étiquette sur le pot de confiture qui permet de pas se tromper entre groseille et framboise, sans avoir besoin de l'ouvrir et de le goûter (le drame!).

    Et puis le petit plus, c'est de pouvoir générer la doc avec doxygen ou autre. Bref, je ne comprend surtout pas pourquoi on doit s'en priver. Après c'est peut-être moins valable quand on développe des applis type gestion ou le nom des variables & méthodes sont assez évocateurs. Enfin je suppose...

  15. #35
    Expert éminent sénior
    Avatar de Paul TOTH
    Homme Profil pro
    Freelance
    Inscrit en
    Novembre 2002
    Messages
    8 964
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 54
    Localisation : France, Paris (Île de France)

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

    Informations forums :
    Inscription : Novembre 2002
    Messages : 8 964
    Points : 28 430
    Points
    28 430
    Par défaut
    Citation Envoyé par Nathanael Marchand Voir le message
    Pour moi ton commentaire n'a pas sa place dans le code, sa place est dans des spécifications fonctionnelles... Le mettre dans le code signifie qu'uniquement le développeur aura connaissance de ca, pas le MOA. Pire que ca, ta règle a de grandes chances d'être en triplon (oui je viens de créer ca) (code + commentaire + specs) et ca augmente encore plus le potentiel de désynchronisation entre les trois.

    Un code correctement construit et nommé accompagné d'une doc (mais pas dans le code) fonctionnelle, ca c'est utile, car même un non codeur peut reprendre la doc !

    PS chipotage: en plus ton code il marche pas, car même avec un montant supérieur à 1M on tombe dans le else qui envoie un TIP
    puisque le sujet déchaîne toujours les passions, je ne résiste pas à y mettre mon grain de sel.

    dernier exemple en date :

    - spécification :
    * un fichier de données est créé avec les commande du jour, le fichier sera nommé "data-yyyy-mm-dd.dat" où yyyy-mm-dd représente la date du jour.
    * les données du jour ne sont pas reprise le lendemain

    - réalisation :
    * $filename = 'data-'.date('Y-m-d').'.dat';
    * if (date('Ymd') != $curdate) { $data = array(); $curdate = date('Ymd'); }

    - réalité : la procédure s'exécute à 00:00 crée un fichier pour J+1 avec les données du jour J

    - modification : $filename = 'data-'.date('Y-m-d', time() - 1 * 60 * 60).'.dat';

    ça c'est un exemple réel (pas en PHP mais peu importe), la création du fichier J+1 perturbe de plus le fonctionne de l'appli, donc pour éviter le bug, sachant qu'il n'y a pas de commande entre 23h et 11h le lendemain, en retirant 1h à la date courante pour calculer le nom du fichier on tombe toujours sur le "bon" jour. Ce n'est pas un problème de spécification mais d'implémentation. Je place très souvent des commentaires sur le code beau et propre initiale qui a été modifié pour corriger un bug car ce bug n'étant pas évident à la lecture du code il est nécessaire d'attirer l'attention du lecteur sur l'importance de la modification.

    allez aussi savoir sans commentaire pourquoi le code est en réalité : $filename = 'data-'.gmdate('Y-m-d', time() + 3 * 60 * 60).'.dat'; !
    Developpez.com: Mes articles, forum FlashPascal
    Entreprise: Execute SARL
    Le Store Excute Store

  16. #36
    Membre éclairé
    Homme Profil pro
    Inscrit en
    Mars 2013
    Messages
    322
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France

    Informations forums :
    Inscription : Mars 2013
    Messages : 322
    Points : 881
    Points
    881
    Par défaut
    Un bon code doit, selon moi, avoir des commentaires fonctionnels ayant un apport supplémentaire.

    Il est évident que du commentaire basique décrivant le code n'est pas intéressant.

  17. #37
    Membre à l'essai
    Homme Profil pro
    Inscrit en
    Décembre 2010
    Messages
    49
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 32
    Localisation : France

    Informations forums :
    Inscription : Décembre 2010
    Messages : 49
    Points : 20
    Points
    20
    Par défaut
    Les commentaires sont importants. Dire que si un code a besoin de commentaire, c’est qu’il faut changer le code lui-même, c’est très con. Certaines lignes de hack ou hardware peuvent nécessiter des explications, exemple très simple l’isqrt de Carmack.

  18. #38
    Inactif  

    Homme Profil pro
    Ingénieur test de performance
    Inscrit en
    Décembre 2003
    Messages
    1 986
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 49
    Localisation : France, Bouches du Rhône (Provence Alpes Côte d'Azur)

    Informations professionnelles :
    Activité : Ingénieur test de performance
    Secteur : High Tech - Éditeur de logiciels

    Informations forums :
    Inscription : Décembre 2003
    Messages : 1 986
    Points : 2 605
    Points
    2 605
    Par défaut
    Bonjour.

    Je suis très controversé sur les commentaires. Je trouve cela très utile et très chiant.

    Quand je découvre un code écrit par une autre personne, c'est sympa d'avoir des commentaires de partout. Ca évite parfois de lire 15 pages de specification

    Par contre quand je code, les commentaires c'est gonflant. Il y a du vert de partout, une fonction de 20 lignes en fait 50, le cadre de travail est exécrable. Il faut scroller sur deux/trois pages, on ne peut pas avoir une vision d'ensemble correcte sur la fonction. Bref c'est comme le code trop aéré, selon moi, tout cela nuit à une bonne maintenance du code. Si on débuge une fonction qui tiens sur l'écran, ce sera plus facile de trouver l'erreur que dans le cas ou il faut scroller et re-scroller et re... A moins d'avoir une mémoire d'einstein.

    Je ne vous parle même pas des projets qui contiennent des fonctions de 100 lignes de code avec 10/15 accolades ouvrantes. Rajouter des commentaires là-dessus, et c'est du grand n'importe quoi. Vous passez plus votre vie à scroller qu'à programmer.

    Donc je suis mitigé.

    Pour la lecture d'un code inconnu, les commentaires, c'est bien.

    Quand on code, on sait ce que l'on fait. Donc commenter ce que l'on fait, ça fait doublon sur le coup. Personnellement, lorsque je code, j'ai aussi hâte de voir le résultat. Parce que commenter un code que je vais modifier 50 fois, donc recommenter 50 fois... J'exagère, mais quand vous codez tous les jours, ça prends des proportions énormes.

    Bref, comment conjurer ces deux aspects.

    Pour ma part :

    un code le plus simple possible. Des nommages explicites et peu de commentaires.
    A côté de cela, je fournis un schéma architectural du projet lorsqu'il est stable (cela permet d'avoir une vision d'ensemble du projet. Je pense que c'est mieux qu'un roman de spécification, qui sera plutôt dédié au concepteur de bibliothèque).
    Lorsque j'ai le temps, je fournis un schéma fonctionnel, histoire d'entrer un peu plus dans les détails du projet.

    Tout cela pour dire que les schémas/diagramme me sont beaucoup plus utiles que du roman/commentaire, lorsque je dois reprendre du code.

    Mais chacun sa méthode. S'il y avait une méthode universelle, on ne sera pas là à épiloguer sur les commentaires.

    L'idéal serait d'avoir un code commenté entièrement, et un code sans commentaire. L'un pour la lecture et la découverte, l'autre pour la maintenance et le débugage. Un IDE du futur quoi.

  19. #39
    Membre averti
    Profil pro
    Inscrit en
    Janvier 2008
    Messages
    214
    Détails du profil
    Informations personnelles :
    Localisation : France

    Informations forums :
    Inscription : Janvier 2008
    Messages : 214
    Points : 310
    Points
    310
    Par défaut
    À lire toutes ces réponses j'en conclus, que quelque soit la durée de vie du code, quelque soit le développeur :
    - Il existe toujours un document de spécification, accessible, qui correspond exactement à ce que fais le programme, et dont la spécification pour le code examiné est identifiable aisément.
    - Toutes les subtilités du langage de programmation utilisé sont parfaitement connues.
    - Tous les algorithmes, pourvus qu'ils soient identifiés, son parfaitement connus.
    - Toutes les API utilisées sont parfaitement connues, dans toutes les versions.

    Donc de toute manière, le commentaire ne sert à pas grand chose, tout développeur code de manière suffisamment claire. En fait si quelqu'un fait remarquer qu'un commentaire aurait été utile pour telle ligne de code, RTFM, ou va te former ?

    Or un code est fait pour rester en vie quelques années, alors même que :
    - telle API n'est plus à la mode
    - tel algorithme était super connu par le développeur, mais en fait très spécifique et trouvable que dans un ouvrage inconnu du développeur lambda
    - un bug a entrainé la correction du code pour que cela fonctionne dans tous les cas, sans que la spécification en soit changée.
    - le développeur n'est pas un spécialiste du langage utilisé, et il existe une meilleure solution que le code existant (et inversement)

    En plus, dire que le bon code n'a pas besoin de commentaire, c'est être présomptueux et déclarer que c'est forcément le bon choix de programmation qui a été fait. Or nous ne sommes jamais à l'abri d'une erreur, ou d'une ignorance.

  20. #40
    Membre expert Avatar de air-dex
    Homme Profil pro
    Inscrit en
    Août 2010
    Messages
    1 653
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 36
    Localisation : France

    Informations forums :
    Inscription : Août 2010
    Messages : 1 653
    Points : 3 773
    Points
    3 773
    Par défaut
    Un bon code doit être compris avec un minimum de commentaires. Des noms suffisamment explicites pour les variables, classes, méthodes, fonctions, etc. peuvent déjà en éviter pas mal. Et puis tant pis si des fois ces noms sont un peu longs. Au pire un bon IDE/éditeur a toujours une fonction d'autocomplétion type "CTRL + Espace" pour compléter rapidement le nom à rallonge en question.

    Me concernant, j'utilise les commentaires pour décrire les grandes étapes de mon code avec un résumé au début de chaque grosse partie pour expliquer ladite partie. Je suis d'accord que certaines grosses parties de codes peuvent être remplacées par des fonctions ou méthodes mais à beaucoup trop morceler le code, on perd en compréhension.

    J'en mets également à certains endroits pour expliquer par exemple que tel ou tel choix peut-être dû à un bug qu'il a fallu fixer avec cette solution particulière : "J'ai fait comme ci plutôt que comme ça sinon il y a tel bug qui se produit". Un genre de "Faut pas toucher à cette partie sinon ça marche plus", mais avec la raison pour laquelle ça ne marcherait pas. Comme par exemple un workaround autour d'un bug (non résolu) d'une librairie (ça m'est déjà arrivé).

    Je pense aussi que maintenir les commentaires à jour au fur et à mesure des modifications du code est une bonne pratique qui se doit d'être respectée. Les commentaires indiquent les choses qui se passent, pas celles qui se sont passées par le passé et qui ne se passent plus dans le présent. C'est bête à dire mais encore faut-il le rappeler.
    "Ils ne savaient pas que c'était impossible alors ils l'ont fait." Mark Twain

    Mon client Twitter Qt cross-platform Windows et Linux. (en cours de développement).

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