IdentifiantMot de passe
Mot de passe oublié ?Je m'inscris ! (gratuit)

Vous êtes nouveau sur Developpez.com ? Créez votre compte ou connectez-vous afin de pouvoir participer !

Vous devez avoir un compte Developpez.com et être connecté pour pouvoir participer aux discussions.

Vous n'avez pas encore de compte Developpez.com ? Créez-en un en quelques instants, c'est entièrement gratuit !

Si vous disposez déjà d'un compte et qu'il est bien activé, connectez-vous à l'aide du formulaire ci-dessous.

Identifiez-vous
Identifiant
Mot de passe
Mot de passe oublié ?
Créer un compte

L'inscription est gratuite et ne vous prendra que quelques instants !

Je m'inscris !

Un code bien écrit a-t-il besoin des commentaires ?
Quelle est la place des commentaires dans votre code ?

Le , par Hinault Romaric
485 commentaires

63PARTAGES

14  20 
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 avez lu gratuitement 4 articles depuis plus d'un an.
Soutenez le club developpez.com en souscrivant un abonnement pour que nous puissions continuer à vous proposer des publications.

Une erreur dans cette actualité ? Signalez-nous-la !

485 commentaires
Commenter Signaler un problème
jmnicolas
Avatar de jmnicolas
Membre éprouvé https://www.developpez.com
Le 10/05/2013 à 22:46
//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 
1
2
3
ExtractDataFromOldSystem();
ConvertOldDataToNewFormat();
LoadFormattedDataToNewSystem();
28  1 
nouknouk
Avatar de nouknouk
Modérateur https://www.developpez.com
Le 10/05/2013 à 23:12
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.
26  1 
Paul TOTH
Avatar de Paul TOTH
Expert éminent sénior https://www.developpez.com
Le 10/05/2013 à 18:30
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 !
24  3 
Avatar de
https://www.developpez.com
Le 10/05/2013 à 18:42
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.
18  2 
Jarodd
Avatar de Jarodd
Membre expérimenté https://www.developpez.com
Le 12/05/2013 à 12:22
Code : Sélectionner tout 
1
2
3
4
//Extraire les données de l’ancien système
//Transformer les données
//Charger les données dans le nouveau système
Code : Sélectionner tout 
1
2
3
4
Extract();
Transform();
Load();
Euh, je suis désolé mais le nom de ces fonctions ne reflêtent pas du tout leurs utilisation décrite dans les commentaires.

Load() ça charge, mais ça charge quoi ? Ah ok, les données dans le nouveau système. Et si je dois écrire une fonction qui charge les données dans l'ancien système, je la nomme comment ? Load2() ? LoadOld() ?

Transform() c'est aussi extrêment précis on comprend de suite de quoi il s'agit : on transforme ! Et on peut la réutiliser dans d'autres programmes, par exemple pour transformer des patates en purée ! Il n'y a plus qu'à espérer que le code soit le même que pour transformer une donnée en autre chose, puisque c'est ce code qui nous servira à comprendre le but de la fonction !

Bref c'est peut-être vrai qu'on peut se passer de commentaires. Mais les exemples sont très mal choisis, et pas convaincants du tout. Quel est l'avantage, au final, de s'en passer ? On va économiser 50 lignes sur un fichiers de plusieurs centaines, trop bien on cva économiser un scroll de la molette Si au moins on diminuait le temps d'exécution du code, mais même pas... Par contre on risque de compliquer la lecture du code ! Je préfère ligne 2 lignes m'expliquant à quoi sert une fonction que me taper les 50 du corps de la fonction !
15  0 
Nathanael Marchand
Avatar de Nathanael Marchand
Rédacteur https://www.developpez.com
Le 10/05/2013 à 19:28
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  0 
benicourt
Avatar de benicourt
Membre régulier https://www.developpez.com
Le 10/05/2013 à 22:08
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.
10  0 
ClaudeBg
Avatar de ClaudeBg
Membre éprouvé https://www.developpez.com
Le 12/05/2013 à 12:55
Salut
-----

Je n'envisage pas un code non commenté, déjà pour les raisons suivantes :

1) Je sais programmer et je sais ce que j'ai programmé. Pourtant quand je relis un ancien programme je suis bien heureux de trouver des commentaires. Ce qui semble évident aujourd'hui ne le sera pas forcément demain.

2) Les commentaires ne coûtent rien et n'allongent pas la durée d'exécution, donc on ne gagne rien en n'en mettant pas

3) L'argument consistant à dire qu'on perd du temps en écrivant des commentaires est une farce : personne n'utilise 100% de son temps à taper du code (il y a un temps de réflexion), et on réfléchit aussi en tapant ses commentaires, voire on s'aperçoit en expliquant ce qu'on a fait qu'il y avait moyen de faire plus simple et plus évident

4) La majorité de ceux prétendant que les commentaires sont inutiles sont les mêmes que ceux qui prétendent qu'établir d'avance le schéma de son programme (pseudo-code, ordinogramme etc) est inutile. Et, de ma propre expérience, ce sont justement ceux-là qui crient au secours en envoyant à debugger des codes illisibles et dépourvus de commentaires. Pour moi, quand je reçois une demande d'assistance avec absence de commentaires, c'est poubelle direct

5) Ceux qui trouvent les commentaires des autres inutiles n'ont simplement qu'à ne pas les lire. Par contre, ceux qui les trouvent utiles ne peuvent pas lire ceux qui ne sont pas présents. Donc, sauf si on est certain que son code ne sera jamais lu par d'autres, il faut au minimum avoir une démarche ouverte.

6) Pour moi, je suis de l'avis diamétralement opposé à celui de l'auteur de l'article. Lui prétend qu'un code suffit pour retrouver les commentaires, et moi j'affirme qu'on doit pouvoir ré-écrire le code à partir des commentaires, si ceux-ci sont bien réalisés. Même un programmeur averti lit et comprend plus efficacement sa langue natale qu'un langage informatique.

7) Les affirmations sont beaucoup trop généralistes à mon avis: Si on peut admettre la pauvreté (pas l'absence) des commentaires dans un langage proche de la syntaxe humaine (genre C#-> Linq), je défie les meilleurs programmeurs de s'y retrouver de façon "naturelle" dans les langages bas niveaux, surtout lorsqu'il s'agit de fonctions manipulant les données de façon complexes (algos mathématiques, conversions, etc).

Ma conclusion est qu'un commentaire inutile ne dérange personne et n'induit aucune perte de performance. Par contre, un commentaire absent peut se révéler dérangeant. On peut donc décider de ne pas commenter, mais conseiller de ne pas le faire est une absurdité monumentale car ce conseil loufoque ne manquera pas d'être pris pour argent comptant par ceux, justement, qui ont le plus intérêt à commenter: les débutants.

A+
Claude
12  2 
Klaim
Avatar de Klaim
Membre expert https://www.developpez.com
Le 10/05/2013 à 18:51
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  1 
iMaTh
Avatar de iMaTh
Membre régulier https://www.developpez.com
Le 14/05/2013 à 9:29
Très souvent on ne travaille pas seul. Donc commenter c'est aider les collègues a comprendre.

La vraie intelligence dans la communication ce n'est pas de dire les autres doivent s'adapter a soit même, mais de faire le maximum pour ce que l'on tente de transmettre soit compris.

Et quand je vois ce genre de citation "Les commentaires c'est inutile", ça met vraiment le doigt sur un gros défaut de l'informaticien : la communication.

Il y a pas que la technique dans la vie !
8  0 
Commenter Signaler un problème