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 :

Citation:

---

//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 :

Citation:

---

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 ?

:fleche: Que pensez-vous de la conclusion de Steve Smith ?

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

:fleche: Quelle place les commentaires occupent dans votre code ?

:fleche: Quels sont vos conseils pour bien commenter son code ou éviter les commentaires superflus ?

Citation:

---

Que pensez-vous de la conclusion de Steve Smith ?

---

Je pense que la conclusion de S. Smith est très intéressante.

Citation:

---

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 ^^

Citation:

---

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.

Citation:

---

Quelle place les commentaires occupent dans votre code ?

---

Malheureusement, mes codes ne sont pas remplis de commentaires bien au contraire ^^

Citation:

---

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).

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 !

Voilà bien un débat taillé sur mesure pour moi :D

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.

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.

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.

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.

Citation:

---

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. :roll:

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.

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).

Citation:

---

Envoyé par CapFlow

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() ? :aie:

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.

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 ... :roll:

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 ?

Citation:

---

Envoyé par Nathanael Marchand

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() ? :aie:

---

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:

---

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

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.

j'ai toujours pensé que les commentaires en programmation non seulement sont superflus et peuvent induire en erreur un programmateur non averti

Perso, je suis du point du même avis que Martin Fowler (don je suis un grand fan :P)! 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....

Citation:

---

Envoyé par alex.buisson

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.

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".

Citation:

---

//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:

---

1 2 3

ExtractDataFromOldSystem(); ConvertOldDataToNewFormat(); LoadFormattedDataToNewSystem();

---