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

Les rubriques (actu, forums, tutos) de Développez
Tags
Réseaux sociaux


 Discussion forum

Sur le même sujet
Le , par Hinault Romaric, Responsable Actualités
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 aimé cette actualité ? Alors partagez-la avec vos amis en cliquant sur les boutons ci-dessous :


 Poster une réponse

Avatar de Linunix Linunix
http://www.developpez.com
Membre expérimenté
le 10/05/2013 18:30
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).
Avatar de Paul TOTH Paul TOTH
http://www.developpez.com
Expert Confirmé Sénior
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 !
Avatar de germinolegrand germinolegrand
http://www.developpez.com
Expert Confirmé Sénior
le 10/05/2013 18:37
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.
Avatar de rawsrc rawsrc
http://www.developpez.com
Modérateur
le 10/05/2013 18:46
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.
Avatar de coolspot coolspot
http://www.developpez.com
Membre éclairé
le 10/05/2013 18:50
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.
Avatar de Klaim Klaim
http://www.developpez.com
Expert Confirmé
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.
Avatar de CapFlow CapFlow
http://www.developpez.com
Membre confirmé
le 10/05/2013 18:55
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).
Avatar de Nathanael Marchand Nathanael Marchand
http://www.developpez.com
Rédacteur/Modérateur
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() ?
Avatar de hakurou hakurou
http://www.developpez.com
Membre régulier
le 10/05/2013 19:36
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.
Avatar de Jitou Jitou
http://www.developpez.com
Membre actif
le 10/05/2013 21:13
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 ...
Offres d'emploi IT
Analyste Programmeur h/f
CDI
Kobaltt - Pays de la Loire - La Roche sur Yon (85000)
Parue le 16/10/2014
Dba sql server h/f
CDI
CAREER BOOSTER - Ile de France - Paris (75000)
Parue le 03/10/2014
CHEF COMPTABLE ET CONTRÔLE DE GESTION H/F
CDI
Grey Consulting - Ile de France - Fleury-Mérogis (91700)
Parue le 16/10/2014

Voir plus d'offres Voir la carte des offres IT
 
 
 
 
Partenaires

PlanetHoster
Ikoula