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. #1
    Responsable .NET

    Avatar de Hinault Romaric
    Homme Profil pro
    Consultant
    Inscrit en
    Janvier 2007
    Messages
    4 570
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : Cameroun

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

    Informations forums :
    Inscription : Janvier 2007
    Messages : 4 570
    Points : 252 372
    Points
    252 372
    Billets dans le blog
    121
    Par défaut Un code bien écrit a-t-il besoin des commentaires ?
    Un code bien écrit a-t-il besoin des commentaires ?
    Quelle est la place des commentaires dans votre code ?


    En programmation, 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.

    Dès les premiers cours de programmation, il est conseillé de « toujours et bien » commenter son code. Les commentaires permettent de facilement comprendre le code et de pouvoir le modifier rapidement.

    Je suis tombé sur un excellent billet de blog de Steve Smith, un développeur .NET, qui estime que le code devrait être écrit de telle manière que sa simplicité élimine la nécessité de la plupart des commentaires. Son article est étoffé de plusieurs citations intéressantes sur les commentaires que je vais reprendre quelques-uns.

    Citation Envoyé par Steve Mcconnell
    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
    Citation Envoyé par P. Graham
    La meilleure façon de faire des programmes faciles à lire n’est pas de les farcir de commentaires [...] Un bon langage de programmation devrait mieux expliquer un logiciel que l’anglais
    Citation Envoyé par Steve McConnell
    Un bon code est sa propre documentation. Lorsque vous êtes sur le point d’ajouter un commentaire, demandez-vous : « Comment puis-je améliorer le code de sorte que les commentaires ne soient plus nécessaires ?» Améliorez le code, puis documentez pour le rendre encore plus clair

    Pour Smith, la meilleure façon d’y parvenir est de nommer les variables et les classes de manière cohérente et explicite. Ecrire de petites méthodes bien nommées. Par exemple, les commentaires :

    //Extraire les données de l’ancien système
    //Transformer les données
    //Charger les données dans le nouveau système
    Ces commentaires sont bien, mais il est préférable de remplacer chaque commentaire avec un nom de méthode explicite :

    Extract();
    Transform();
    Load();

    Citation Envoyé par Martin Fowler
    Lorsque vous sentez le besoin d'écrire un commentaire, essayez d'abord de modifier le code de sorte que tout commentaire devient superflu
    « Les commentaires doivent être généralement évités si le code peut dire ce qu’il fait. 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 », conclut Smith.


    Source : Billet de blog Steve Smith


    Et vous ?

    Que pensez-vous de la conclusion de Steve Smith ?

    Un code de bonne qualité doit-il systématiquement avoir des commentaires ?

    Quelle place les commentaires occupent dans votre code ?

    Quels sont vos conseils pour bien commenter son code ou éviter les commentaires superflus ?
    Vous souhaitez participer aux rubriques .NET ? Contactez-moi

    Si déboguer est l’art de corriger les bugs, alors programmer est l’art d’en faire
    Mon blog, Mes articles, Me suivre sur Twitter
    En posant correctement votre problème, on trouve la moitié de la solution

  2. #2
    Membre confirmé

    Homme Profil pro
    Etudiant
    Inscrit en
    Juillet 2012
    Messages
    108
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France, Bouches du Rhône (Provence Alpes Côte d'Azur)

    Informations professionnelles :
    Activité : Etudiant
    Secteur : High Tech - Produits et services télécom et Internet

    Informations forums :
    Inscription : Juillet 2012
    Messages : 108
    Points : 573
    Points
    573
    Par défaut
    Que pensez-vous de la conclusion de Steve Smith ?
    Je pense que la conclusion de S. Smith est très intéressante.
    Les commentaires doivent être généralement évités si le code peut dire ce qu’il fait
    Car la phrase précédente veut tout dire ^^
    Un code de bonne qualité doit-il systématiquement avoir des commentaires ?
    Selon moi, un code de bonne qualité, doit posséder des commentaires, bien que le code soit tout de même compréhensible, il est intéressant de mettre des commentaires, pour les débutants :
    La plupart d'entre nous avons appris la subtilité d'un langage en regardant, du code, du code et encore du code, donc, je pense que mettre des commentaires, donne de la curiosité aux débutants.

    Quelle place les commentaires occupent dans votre code ?
    Malheureusement, mes codes ne sont pas remplis de commentaires bien au contraire ^^
    Quels sont vos conseils pour bien commenter son code ou éviter les commentaires superflus ?
    Et bien je pense que pour bien commenter un code, il faut déjà bien comprendre ce que l'on a codé . Par contre concernant les commentaires superflues, je pense qu'il faut éviter de commenter un code basique(c'est a dire aussi compréhensible pour les débutants).
    Le paradigme de chacun ne dépend pas de lui, mais de son éducation...

    Le mot donne à la pensée son existence la plus haute et la plus noble.
    Spinoza

    Quiconque n'est pas choqué par la théorie quantique ne la comprend pas.
    Niels Bohr

    http://isocpp.org/

  3. #3
    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
    faut-il réellement relancer un nième pseudo-débat sur les commentaires ?

    tout cela en allant pêcher un blog de octobre 2010 !
    Developpez.com: Mes articles, forum FlashPascal
    Entreprise: Execute SARL
    Le Store Excute Store

  4. #4
    Membre expert

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

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

    Informations forums :
    Inscription : Octobre 2010
    Messages : 738
    Points : 3 892
    Points
    3 892
    Par défaut
    Voilà bien un débat taillé sur mesure pour moi

    Je vais abonder dans le sens de ces messieurs, pour moi un bon code est un code auto-documenté. Je précise tout de même que les commentaires sont indispensables lorsque le code est insuffisant pour se documenter lui-même.

  5. #5
    Invité
    Invité(e)
    Par défaut
    Les commentaires sont indispensables lors du travail en équipe mais aussi pour une relecture du code plus rapide. Exemple lorsque vous avez beaucoup de conditions il est difficile d'y revenir 2 ans après sans oubliez à quoi elles servent. Une petite ligne de commentaire expliquant la condition est agréable.
    Tout mon code est commenté car si un jour je repasse le projet à quelqu'un d'autre il ne mettra pas des heures à comprendre ce qui à été fait et pourquoi cela à été fait, il aura les grandes lignes du code écrite en français.

    Merci de commenter pour ceux qui reprennent le code d'un autre.

  6. #6
    Expert éminent sénior
    Avatar de rawsrc
    Homme Profil pro
    Dev indep
    Inscrit en
    Mars 2004
    Messages
    6 142
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 47
    Localisation : France, Bouches du Rhône (Provence Alpes Côte d'Azur)

    Informations professionnelles :
    Activité : Dev indep

    Informations forums :
    Inscription : Mars 2004
    Messages : 6 142
    Points : 16 545
    Points
    16 545
    Billets dans le blog
    12
    Par défaut
    Il est évident que les commentaires ne doivent pas enfoncer des portes ouvertes par contre ils peuvent très utiles pour saisir rapidement certains détails algorithmiques (optimisation, raccourci...)

    C'est toujours la même chose : faut savoir peser le pour, le contre, la difficulté et s'adapter en fonction.

  7. #7
    Membre éprouvé
    Profil pro
    Inscrit en
    Mars 2012
    Messages
    371
    Détails du profil
    Informations personnelles :
    Localisation : France

    Informations forums :
    Inscription : Mars 2012
    Messages : 371
    Points : 1 002
    Points
    1 002
    Par défaut
    Honnêtement, faisant du Dev Java. Du commentaire de code j'en fait très peu.

    Je me contente d'essayer de bien structurer mes classes et découper mes méthodes. De faire de la JavaDoc pertinente sur mes méthodes avec des nom de méthode et de variable adéquat et compréhensible sur sa nature (j'évite les arg1, arg2, arg3).

    Pour en gros grâce à la lecture du nom de la méthode et à la Javadoc, la compréhension du code en découle.

  8. #8
    Membre expert
    Avatar de Klaim
    Homme Profil pro
    Développeur de jeux vidéo
    Inscrit en
    Août 2004
    Messages
    1 717
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France

    Informations professionnelles :
    Activité : Développeur de jeux vidéo
    Secteur : High Tech - Éditeur de logiciels

    Informations forums :
    Inscription : Août 2004
    Messages : 1 717
    Points : 3 344
    Points
    3 344
    Par défaut
    faut-il réellement relancer un nième pseudo-débat sur les commentaires ?

    tout cela en allant pêcher un blog de octobre 2010 !
    Meme question.

    En plus on ne fait ici pas la difference entre les commentaires explicitant le comportement et l'usage d'une interface et les commentaires dans l'implementation de cette interface. C'est tellement different que ca n'a presque rien a voir.

  9. #9
    Membre actif Avatar de CapFlow
    Homme Profil pro
    Étudiant
    Inscrit en
    Octobre 2011
    Messages
    72
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France

    Informations professionnelles :
    Activité : Étudiant

    Informations forums :
    Inscription : Octobre 2011
    Messages : 72
    Points : 219
    Points
    219
    Par défaut
    Il a dans un certain sens raison mais ça dépend aussi de la taille du code.

    Par exemple quand je vois un code où des fonctions appellent des fonctions qui elles-mêmes appellent des fonctions etc ... c'est incompréhensible. (ça peut être le but dans une version release, mais côté prod les commentaires sont indispensables).

  10. #10
    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 CapFlow Voir le message
    Par exemple quand je vois un code où des fonctions appellent des fonctions qui elles-mêmes appellent des fonctions etc ... c'est incompréhensible.
    C'est pas le principe d'un programme ce que tu décris là ? A moins que tu mettes tout dans une grosse fonction Main() ?

  11. #11
    Membre régulier
    Homme Profil pro
    Développeur Web
    Inscrit en
    Décembre 2006
    Messages
    105
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France, Bas Rhin (Alsace)

    Informations professionnelles :
    Activité : Développeur Web

    Informations forums :
    Inscription : Décembre 2006
    Messages : 105
    Points : 119
    Points
    119
    Par défaut
    C'est vrai qu'on dit qu'un code bien fait peut se passer de commentaire mais bon, il est quand même plus simple de lire une phrase résumant une fonction/méthode que de lire plusieurs lignes.
    De même que dans ma boite si on se mettait à ne plus écrire de commentaire, il y aurait des gens qui finiraient chauves...
    La compréhension d'un code dépend également du niveau du dev et de ce fait les coms sont utiles.
    J'ai réussi a imposer l'utilisation de javadoc et franchement les gens galèrent moins et peuvent suivre même s'ils ont pas tous le même niveau.

  12. #12
    Membre confirmé
    Homme Profil pro
    Ingénieur développement logiciels
    Inscrit en
    Janvier 2007
    Messages
    185
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 53
    Localisation : France

    Informations professionnelles :
    Activité : Ingénieur développement logiciels

    Informations forums :
    Inscription : Janvier 2007
    Messages : 185
    Points : 469
    Points
    469
    Par défaut
    Je suis 100% d'accord avec Steve Smith à ceci près que pour moi les commentaires sont essentiels au moins pour rappeler ce que l'on met en oeuvre par rapport aux spécifications détaillées du projet après il est primordiale de nommer explicitement ses variables et autres classes. Je rappel que le programme ne sera pas moins performant si les noms sont à rallonge. Abolir aussi la coupure des lignes à 80 colonnes comme je le vois encore trop souvent, nous somme en 2013 et les moniteurs peuvent afficher plus de 80 caractère par lignes !!! Enfin avec des langages objets il faut utiliser le paradigme des objets ! Cela parait évident dit comme ça mais parfois on se pose des questions et on se demande ce qu'apprennent vraiment les étudiants en informatiques de nos jours ...

  13. #13
    Membre chevronné

    Profil pro
    Account Manager
    Inscrit en
    Décembre 2006
    Messages
    2 301
    Détails du profil
    Informations personnelles :
    Localisation : France, Savoie (Rhône Alpes)

    Informations professionnelles :
    Activité : Account Manager

    Informations forums :
    Inscription : Décembre 2006
    Messages : 2 301
    Points : 1 752
    Points
    1 752
    Par défaut
    Bonsoir,
    pour ma part, j'utilise les commentaires pour deux choses :
    1. Mettre des titres pour mieux visualiser des sous-parties.
    2. Faire la documentation technique de mes codes.


    C'est tout de même pratique. Pour le reste, je pense aussi qu'un code doit se comprendre de lui-même en morcelant au possible. Mais est-ce toujours faisable en vrai ?

  14. #14
    Membre actif Avatar de CapFlow
    Homme Profil pro
    Étudiant
    Inscrit en
    Octobre 2011
    Messages
    72
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France

    Informations professionnelles :
    Activité : Étudiant

    Informations forums :
    Inscription : Octobre 2011
    Messages : 72
    Points : 219
    Points
    219
    Par défaut
    Citation Envoyé par Nathanael Marchand Voir le message
    C'est pas le principe d'un programme ce que tu décris là ? A moins que tu mettes tout dans une grosse fonction Main() ?
    On ne parle surement pas de la même chose.
    Je suis d'accord avec toi, c'est un peu le principe d'un programme. Mais quand ça se joue sur 2-7 lignes pour chaque fonction avec les paramètres qui se passent de fonctions en fonctions ... tu te mélanges les pinceaux.

    Code : Sélectionner tout - Visualiser dans une fenêtre à part
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    var ex = {
    	main: function (callback, str) {
    		var number = Math.floor(Math.random() * 10) + Math.floor(Math.random() * -10);
    		console.log(number)
    		this.callWithContext(callback, this.whichText(number, str));
    	},
    	callWithContext: function (callback, number, finalStr) {
    		callback.call(this.theContext);
    		console.log(this.theContext.finalValue + ": " + this.whichText(number, finalStr));
    	},
    	whichText: function (number, str) {
    		return number < 0 ? str : "it's damage";
    	},
    	theContext: {
    		firstValue: 5,
    		secondValue: 10
    	}
    };
    ex.main(function () { this.finalValue = this.firstValue + this.secondValue }, "It's ok !");
    C'est un code un peu bateau (peut être pas fonctionnel, c'est tard :p ) mais c'est un petit exemple

  15. #15
    Membre régulier Avatar de benicourt
    Homme Profil pro
    Formateur en informatique
    Inscrit en
    Août 2008
    Messages
    41
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 49
    Localisation : France, Tarn (Midi Pyrénées)

    Informations professionnelles :
    Activité : Formateur en informatique
    Secteur : High Tech - Éditeur de logiciels

    Informations forums :
    Inscription : Août 2008
    Messages : 41
    Points : 112
    Points
    112
    Par défaut
    Certains algorithmes sont relativement complexes. On a beau donner des noms explicites à ses variables et fonctions, il reste qu'un commentaire permet à d'autres de s'approprier plus facilement le code, et à l'auteur, de se rappeler de ce qu'il a produit quelques mois, voire quelques années auparavant.
    Mais il est vrai aussi qu'il vaut mieux un code très simple, qu'un autre très complexe bourré de commentaires. Les deux aspects ne sont pas incompatibles.

  16. #16
    Nouveau Candidat au Club
    Homme Profil pro
    Urbaniste
    Inscrit en
    Janvier 2012
    Messages
    1
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : Algérie

    Informations professionnelles :
    Activité : Urbaniste
    Secteur : Bâtiment

    Informations forums :
    Inscription : Janvier 2012
    Messages : 1
    Points : 0
    Points
    0
    Par défaut commentaire en pogrammation
    j'ai toujours pensé que les commentaires en programmation non seulement sont superflus et peuvent induire en erreur un programmateur non averti

  17. #17
    Membre du Club
    Inscrit en
    Mai 2010
    Messages
    23
    Détails du profil
    Informations forums :
    Inscription : Mai 2010
    Messages : 23
    Points : 45
    Points
    45
    Par défaut
    Perso, je suis du point du même avis que Martin Fowler (don je suis un grand fan )! Des j'aboutis à un ensemble de code ou je me dis qu'il falloir faire une doc ou commenter pour expliquer les interactions ou les algos, alors c'est qu'il est temps de ré-architecturer pour rendre les chose plus limpides....

    Ajouter des commentaires, c'est ajouter du bruit. Après il faut maintenir les commentaires et le code, 2x + de taf.... Non merci!
    Par contre, il faut aussi avoir des collègues qui partage cette vision. sinon vous vous heurtez au mur des fan de la spec en doc, du gliffy etc....

  18. #18
    Membre actif
    Homme Profil pro
    Développeur
    Inscrit en
    Décembre 2008
    Messages
    101
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France, Isère (Rhône Alpes)

    Informations professionnelles :
    Activité : Développeur

    Informations forums :
    Inscription : Décembre 2008
    Messages : 101
    Points : 256
    Points
    256
    Par défaut
    Citation Envoyé par alex.buisson Voir le message
    Ajouter des commentaires, c'est ajouter du bruit.
    C'est faux. Les commentaires n'ont pas être nombreux, il faut juste qu'ils décrivent l'intention. Le code ne dira jamais autre chose que ce qu'il fait alors que les commentaires décrivent l'intention du développeurs, précise des points particuliers.

    Le code répond à la question : « Comment ? »
    Les commentaires répondes à la question : « Pourquoi ? »

    Il y a eu une discussion intéressante à ce sujet sur linuxfr, il y a peu.

  19. #19
    Membre habitué
    Homme Profil pro
    Développeur Web
    Inscrit en
    Avril 2012
    Messages
    50
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France, Hauts de Seine (Île de France)

    Informations professionnelles :
    Activité : Développeur Web

    Informations forums :
    Inscription : Avril 2012
    Messages : 50
    Points : 186
    Points
    186
    Par défaut
    Les IDE que j'utilise (Netbeans, phpStorm) ont besoin de commentaires phpdoc bien rédigés pour fonctionner correctement (autocomplétion, documentation dans les popups...). Donc mes codes sont tous commenté en phpdoc, avec parfois quelques commentaires en ligne supplémentaire pour les trucs que je n'ai pas réussi à faire de manière évidente et dont je me dit "si un collègue reprend ça dans un an il risque de ne pas comprendre pourquoi j'ai fait ça".

  20. #20
    Membre éprouvé Avatar de jmnicolas
    Homme Profil pro
    Développeur informatique
    Inscrit en
    Juin 2007
    Messages
    427
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 45
    Localisation : France

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

    Informations forums :
    Inscription : Juin 2007
    Messages : 427
    Points : 976
    Points
    976
    Par défaut
    //Extraire les données de l’ancien système
    //Transformer les données
    //Charger les données dans le nouveau système

    Extract();
    Transform();
    Load();
    L'auteur ferait bien de suivre ses propres conseils :

    Code : Sélectionner tout - Visualiser dans une fenêtre à part
    1
    2
    3
    ExtractDataFromOldSystem();
    ConvertOldDataToNewFormat();
    LoadFormattedDataToNewSystem();
    The greatest shortcoming of the human race is our inability to understand the exponential function. Albert A. Bartlett

    La plus grande lacune de la race humaine c'est notre incapacité à comprendre la fonction exponentielle.

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