Un code bien écrit a-t-il besoin des commentaires ?

**skududufru** · 13/05/2013, 11h38

Oui pour moi il faut des commentaires même si le code est super propre. ça permet en autre de gagner du temps quand on a besoin de replonger son nez dans des vieux fichiers.

**r0d** · 13/05/2013, 12h24

Pour ma part, j'utilise de plus en plus les commentaire pour expliquer des choix. Pourquoi ce conteneur (liste, tableau, arbre...), récursif ou itératif, héritage ou agrégation, foncteur ou fonction lambda, etc. Ou un choix de conception (pourquoi ce D.P., pourquoi ce constructeur ne respecte pas RAII, pourquoi une classe virtuelle pure alors qu'à première vue il n'y en a pas besoin, etc.), avec souvent des liens vers des pages qui expliquent le design choisi.

**LaMeule** · 13/05/2013, 12h54

Cela dépend aussi si on est seul ou non sur un projet, car chacun code d'une façon différente.
Perso, étant plusieurs sur un projet, qd je passe sur un bout de code qui n'est pas le mien, je suis content d'avoir des commentaires dans le début de la méthode afin de comprendre à quoi elle sert, son résultat et les paramètres à lui donner à manger, mais aussi dans le code afin de comprendre la logique mis en place.

**Jean-Georges** · 13/05/2013, 13h23

En nommant bien ses variables et fonctions, on se passe aisément d'une grande partie de commentaires. Par exemple, avec une fonction :

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
getPhotosFromArticle(article)
{
    ....
}

Pas besoin de lire le contenu de la fonction pour comprendre ce qu'elle fait, comment l'utiliser et ce qu'elle renvoie.

**Pergos** · 13/05/2013, 13h29

Pour ma part, en tant que grand fan DU bouquin de "l'Oncle Bob" (Clean Code, de Martin Fowler), même si je ménage la chèvre et le choux à longueur de journée, je suis ce précepte : moins il y a besoin de commentaire, plus les commentaires nécessaires deviennent visibles.

Du coup, lorsque j'en mets, je ne me prive pas sur les commentaires (avec force exemple et autres), tout en faisant en sorte que mon code n'en ait pas besoin dans 90% des cas.

Mais c'est une sacré discipline de choisir des noms "justes" pour les variables/attributs, les fonctions/méthodes, etc...
("[le nom] doit être "juste" comme un pièce en or sonne juste parce qu'elle contient exactement la bonne quantité d'or par rapport à sa valeur")

**DevTroglodyte** · 13/05/2013, 13h44

Envoyé par Jean-Georges

En nommant bien ses variables et fonctions, on se passe aisément d'une grande partie de commentaires. Par exemple, avec une fonction :

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
getPhotosFromArticle(article)
{
    ....
}

Pas besoin de lire le contenu de la fonction pour comprendre ce qu'elle fait, comment l'utiliser et ce qu'elle renvoie.

C'est utopique que de penser qu'il est toujours possible d'avoir des noms adaptés (tout en restant lisibles... si les noms adaptés atteignent les 50 caractères, ça va être joli à relire...)

Sans compter que si pour nous, ils semblent logiques (normal, on a écrit le code), ça ne le sera pas forcément pour quelqu'un d'autre. Laisser des commentaires soit globaux pour expliquer vaguement ce que fait une méthode relativement simple, soit précis pour détailler un passage ardu, pour moi, c'est le minimum. Et ofc, la javadoc / équivalent associé surtout si la brique logicielle est destinée à être réutilisée.

Lors de ma précédente mission j'ai du replonger dans un code écrit il y a plus de 10 ans, non commenté, mal foutu de base, et les évolutions sur 10ans n'ont rien amélioré, au contraire... Une horreur. On passe plus de temps a tenter de piger par où on passe qu'a réellement coder / debugger. J'ai regretté l'absence de documentation (les rares commentaires trouvés ne servaient a rien étant donné qu'ils se contentaient de paraphraser le nom de la méthode qu'ils étaient sensés décrire).

Alors oui, les commentaires, c'est bon, mangez en. Pas trop sinon ça tombe direct sur le ventre, mais ne serait-ce que pour penser aux types qui un jour reprendront le code...

**Skyou** · 13/05/2013, 13h50

Bonjour les gens.

Perso, ma méthodologie de travail m'impose des commentaires :
Quand je code une fonction/classe, je commence par écrire mes commentaires :
- un commentaire pour décrire ce que va faire la fonction ou ce à quoi sert la classe (ça me permet de leur trouver un petit nom et de vérifier que c'est bien utile, accessoirement)
- des commentaires pour chaque bloc d'actions de la fonction (j'ai besoin de ça, d'abord je fais ça, ensuite ça pis je renvois ça parce que c'est ce que je veux)

Ça a deux avantages : faire une pause réflexion/méthodologie avant de coder et laisser du commentaire au final.
Parce que j'ai fait français première langue, pas Java ou .Net ou autre

Il sera toujours plus rapide de lire du texte dans sa langue maternelle que dans son langage maternel !

Et vivent les commentaires !

G.

**martopioche** · 13/05/2013, 14h10

Envoyé par Jean-Georges

En nommant bien ses variables et fonctions, on se passe aisément d'une grande partie de commentaires. Par exemple, avec une fonction :

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
getPhotosFromArticle(article)
{
    ....
}

Pas besoin de lire le contenu de la fonction pour comprendre ce qu'elle fait, comment l'utiliser et ce qu'elle renvoie.

Quel est le comportement lorsque article = null/void ? Quel comportement lorsque size(article) = 10 To ? Quelle est la valeur de retour quand il n'y a pas de photos (liste vide, null/void ? ) ?

**martopioche** · 13/05/2013, 14h14

Envoyé par DevTroglodyte

Lors de ma précédente mission j'ai du replonger dans un code écrit il y a plus de 10 ans, non commenté, mal foutu de base, et les évolutions sur 10ans n'ont rien amélioré, au contraire... Une horreur. On passe plus de temps a tenter de piger par où on passe qu'a réellement coder / debugger. J'ai regretté l'absence de documentation (les rares commentaires trouvés ne servaient a rien étant donné qu'ils se contentaient de paraphraser le nom de la méthode qu'ils étaient sensés décrire).

Alors oui, les commentaires, c'est bon, mangez en. Pas trop sinon ça tombe direct sur le ventre, mais ne serait-ce que pour penser aux types qui un jour reprendront le code...

Je trouve que ce post de Michael Nygard illustre tout le problème de code qui doit vivre plus de 6 mois : https://twitter.com/mtnygard/status/332131878830211073

Mon opinion est que le code doit s'exprimer au mieux, mais que le commentaire doit expliquer ce que le code ne peut dire. Plus en détail : http://www.labasland.net/201203/pert...sibilite-code/

Invité · 13/05/2013, 14h55

Envoyé par Jean-Georges

En nommant bien ses variables et fonctions, on se passe aisément d'une grande partie de commentaires.

On peut, mais on a le même problème qu'avec les commentaires :

- que se passe-t-il si la fonction évolue. Même avec les outils de refactoring, la plupart des développeurs ne feront pas évoluer le nom, et si la fonction ReadFromTable() se trouve ne plus lire, et ne pas aller dans un tableau, son nom devient pire qu'un mauvais commentaire
- les noms étant généralement courts, leur qualité dépend de la qualité de l'expression du développeur d'origine, et malheureusement, les developpeurs ne sont pas toujours des littéraires... Et là on se retrouve avec des noms en franglais avec un anglais approximatif, des termes gratuitement techniques, mais parfaitement incompréhensibles.

A tout prendre, je crois que je préfère les commentaires que les noms trop explicites, dont on se demande toujours s'ils sont corrects, pensés, tout ça, ou malvenus, plus à jour, mal traduits...

Francois

**Couette** · 13/05/2013, 15h06

Je pense que cela est bien utile... un code peut être bien écrit ET commenté. C'est pratique. L'exemple pour moi ne reflète pas la réalité... je m'explique :

Il faut se mettre dans le contexte, nous pouvons écrire un code et il se peut qu'il stagne pendant quelques semaines ou mois ! Si le code est un jour repris (par vous ou un collègue), les commentaires sont un gain de temps non négligeable ! De plus, si vous avez rencontré des soucis durant le développement, les commentaires servent à informer la personne qui reprendra le code. Cela servira aussi à lui ou elle d'éviter de faire la même erreur ! Tout est un gain de temps !

**Luckyluke34** · 13/05/2013, 15h55

Les commentaires représentent une source importante de coût et de risque, si bien que chaque fois que je peux m'en passer, je leur préfère un découpage et un nommage du code clair et auto-documentant (pas très français ça

).

Risques associés aux commentaires :

Désynchronisation avec le code à chaque fois qu'on modifie celui-ci => risque de bugs (Je fais confiance aux commentaires... manque de pot la fonction ne faisait pas exactement ça), de blocage (Dois-je croire le code ou les commentaires ?) ou de gaspillage de temps (Jusqu'où dois-je aller dans la relecture de ce code pour voir s'il correspond bien aux commentaires ?)
Les commentaires ne sont pas toujours visibles de partout contrairement aux noms de variables, méthodes, classes : certains peuvent nous échapper
Les outils de refactoring qui facilitent la vie dans un IDE (rename, extract method, etc.) prennent peu ou pas en charge les commentaires => le refactoring ajoute au risque de désynchronisation

Coûts liés aux commentaires :

Coût d'écriture
Coût d'actualisation : resynchroniser les commentaires avec la réalité du code
Coût de nettoyage : supprimer les commentaires obsolètes

Bien sûr, il y a des situations où on peut difficilement se passer de commentaires :

A l'intérieur d'une méthode, commenter un algorithme/hack technique peu intuitif pour le commun des mortels
Documenter une API publique à destination d'utilisateurs/développeurs externes ne pouvant bénéficier d'un apprentissage du code in vivo dans l'équipe de dev

**DevTroglodyte** · 13/05/2013, 16h38

Envoyé par Luckyluke34

Les commentaires représentent une source importante de coût et de risque, si bien que chaque fois que je peux m'en passer

Si tu veux j'ai sur une clé usb une classe de 13k lignes de code java non commenté, non documenté, et utilisant une vieille version du FW java de WebSphereMQ.

, je leur préfère un découpage et un nommage du code clair et auto-documentant (pas très français ça

).

L'éternel souci, c'est : est ce que ce qui est clair pour celui qui est à l'origine du code va l'être pour le type qui va passer après (et quand je dis après, c'est suffisament longtemps pour que le dev d'origine ne soit plus là pour le débloquer)

Les commentaires, c'est comme la spec et la doc qui vont avec l'appli : ça se maintient a jour, c'est nécessaire, mais ça doit être suffisament clair et épuré pour que n'importe qui puisse la lire sans mal de tête (donc, point trop n'en faut, mais il en faut).

**Luckyluke34** · 13/05/2013, 17h11

Envoyé par DevTroglodyte

Si tu veux j'ai sur une clé usb une classe de 13k lignes de code java non commenté, non documenté, et utilisant une vieille version du FW java de WebSphereMQ.

Si c'est du code bien découplé, dont les classes et méthodes ne dépassent pas une dizaine de lignes, avec un nommage révélant leur intention et qui n'utilisent pas des hacks de fou, je ne vois pas où est le problème.

Attention, bien souvent il ne s'agit pas de passer à la trappe la description que pourraient véhiculer des commentaires mais d'essayer de faire porter cette description par le nommage judicieux d'une classe/méthode supplémentaire qui va en plus permettre de rendre le code davantage modulaire.

Ex :

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
6
7
public void MaMethodeDe70Lignes() {
// Do X
(30 lignes de code)

// Do Y
(40 lignes de code)
}

devient :

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
public void MaMethode() {
DoX();

DoY();
}

**r0d** · 13/05/2013, 17h44

Envoyé par Luckyluke34

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
6
7
public void MaMethodeDe70Lignes() {
// Do X
(30 lignes de code)

// Do Y
(40 lignes de code)
}

devient :

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
public void MaMethode() {
DoX();

DoY();
}

Houlaaa, vous prenez bien des risques. Ou alors vous ne connaissez pas encore cette partie du forum.
Avec la manipulation que vous proposez, vous perdez au moins 2 cycles et 2 changements de contexte. Pour peu que MaMethode() soit appelée plus de 3 fois dans le programme, vous êtes sûr de perdre votre compatibilité CPC6128. Nul doute que la vieille garde du forum saura trouver les mots justes afin de punir une telle désinvolture

**reduc** · 13/05/2013, 17h55

Je me considère débutant en programmation. Personnellement, je crois que l'inclusion de commentaires est importante, car au cours de ma modeste expérience, j'ai fait la constatation suivante:

Il est bien plus difficile de lire que d'écrire du code.

Un code bien commenté est beaucoup facile à comprendre.

**Neckara** · 13/05/2013, 18h08

Envoyé par r0d

Houlaaa, vous prenez bien des risques. Ou alors vous ne connaissez pas encore cette partie du forum.
Avec la manipulation que vous proposez, vous perdez au moins 2 cycles et 2 changements de contexte. Pour peu que MaMethode() soit appelée plus de 3 fois dans le programme, vous êtes sûr de perdre votre compatibilité CPC6128. Nul doute que la vieille garde du forum saura trouver les mots justes afin de punir une telle désinvolture

De toute façon, je trouve que MaMethodeDe70Lignes(), DoX() et DoY() ne sont pas des noms vraiment explicites

Plus sérieusement, le fait de tout découper en petites fonctions bien découpée, etc. c'est pas mal, mais toujours est-il que sans commentaires, s'il faut lire 10 000 lignes de codes pour comprendre que l'affichage doit se faire impérativement dans le thread principal sinon ça plante, que ce soit découpé ou non en petites fonctions, il reste toujours (presque) autant de lignes à lire. Or cela aurait pu être évité par un simple commentaire d'une ligne.

Personnellement, je pars du principe qu'on a pas à relire un code pour pouvoir l'utiliser mais qu'il faut lire la documentation.
Or, il y a très souvent des petites subtilités à expliquer (si resultat pas trouvé, retourne null, en cas d'erreurs fait ceci...).

Pour l'actualisation, la désynchronisation, j'ai une solution toute simple : je ne commente une classe que lorsque je pense qu'elle est à peu près stable.
Et généralement, le prototype ne changeant que très rarement, les modifications de commentaires se résument souvent à supprimer des @todo ou des @warning

Après, commenter un code ne prend pas tant de temps que cela, par contre relire tout un code...

Invité · 13/05/2013, 19h20

Envoyé par r0d

Pour peu que MaMethode() soit appelée plus de 3 fois dans le programme, vous êtes sûr de perdre votre compatibilité CPC6128. Nul doute que la vieille garde du forum saura trouver les mots justes afin de punir une telle désinvolture

Vieille garde? On a dit vieille garde?
... no one expects the Spanish Inquisition...

Sérieusement, ce qui peut être fautif dans le principe général : "aucune méthode de plus de N lignes", ce ne sont pas les cycles qu'on va perdre mais le fait que 70 lignes de code, s'exécutant de manière séquentielle, dans une seule fonction, sont nettement plus faciles à lire, comprendre, et débuguer que 7 méthodes "uniques mais surement réutilisables un jour, enfin peut être" de 10 lignes, éparpillées dans trois modules distincts, avec des noms qui ne sont pas forcément si évocateurs pris hors contexte.

Et si on applique un peu trop servilement ces principes de découplage (comme avec une application trop naive du principe de responsabilité unique), on se retrouve, dès que le programme devient un peu gros, un peu ancien, avec des verrues, avec ces abominables hiérarchies de classes qui donnent l'impression d'avoir été pensées par un bègue sous acide...

Comme beaucoup d'autres l'ont dit, un code doit rester lisible, et, veut veut pas, il est plus confortable de lire un roman qu'un programme dont vous êtes le héros...

Pis bon, Rod, se moquer des vieux alors qu'on va encore nous repousser l'âge de NOTRE retraite bien méritée, sur ce forum ~~peuplé de crétins acnéiques~~ (ah zut) fréquenté par de jeunes programmeurs ~~incapables de conjuguer au passé composé les verbes du premier groupe~~ (ah ben zut encore) qui n'ont pas toujours pour le grand âge le respect que celui ci mérite ~~parce que bon, les jeunes, comme je dis toujours, il leur faudrait une bonne guerre~~ (ah ben qu'est ce que j'ai ce soir) c'est pas gentil, non c'est pas gentil...

Francois

**Nathanael Marchand** · 13/05/2013, 19h31

Envoyé par DevTroglodyte

Si tu veux j'ai sur une clé usb une classe de 13k lignes de code java non commenté, non documenté, et utilisant une vieille version du FW java de WebSphereMQ.

Ca c'est un bon exemple qu'un code pourri a besoin de commentaires pour être compris. Et pas qu'un code propre n'a pas besoin de commentaires

**andry.aime** · 13/05/2013, 20h14

Envoyé par satenske

Personnellement, je pense que les commentaires, c'est comme le café, faut savoir les doser. Pas assez, ça n'a pas de gout, c'est mauvais. Trop, ben on a du mal à digérer tout ça.

Ben là tu parles d'une vérité générale, tous ceux qu'on mange,qu'on utilise,qu'on fait,... doit être bien doser ou modérer

.