En programmation, des variables bien nommées valent mieux qu'un bon commentaire,
Qu'en pensez-vous ?

Le , par Michael Guilloux

0PARTAGES

8  2 
On a tendance à dire, dans les bonnes pratiques de la programmation, que les commentaires permettent de rendre un code clair et facile à comprendre pour les autres développeurs qui devront en hériter. Cela permettrait également au programmeur de se repérer lui-même facilement dans son code lors de la maintenance.

Si cette opinion est largement partagée et les commentaires sont utilisés par la grande majorité des programmeurs, il existe toutefois des personnes qui ont un regard tout autre vis-à-vis des commentaires.

Comme l’a défendu et démontré par un exemple sur le blog Simple programmer, un développeur a soutenu que les commentaires sont plutôt des choses à éviter. Il était au départ un grand adepte des commentaires avant de basculer radicalement à l’opposé suite à certaines découvertes. Après avoir lu les bouquins « Complete Code » de Steve McConnell et « Clean Code » de Robert C. Martin, il réalise que l’utilisation des commentaires est une pratique plus nuisible qu’utile.

Il découvre aussi qu’il utilisait des commentaires dans ses codes pour deux raisons. La première, c’est qu’il ne nommait pas les choses d’une manière suffisamment claire de sorte à rendre inutile les commentaires explicatifs. La deuxième est que les méthodes et fonctions, qu’il utilisait dans ses codes, étaient trop larges et donc avaient besoin d’explication supplémentaire.

« J'avais cru que je faisais un bon travail, et que j'étais un programmeur consciencieux en écrivant des commentaires pour expliquer mon code et le rendre plus facile à comprendre pour le prochain développeur ». A-t-il dit. « Mais, quand j’ai commencé à appliquer ce que j'ai appris dans le Complete Code, et commencé à écrire du code qui était souvent plus clair que les commentaires que j'écrivais avant, j'ai réalisé que je faisais une faveur plus grande à tous les développeurs qui hériteraient de mon code que d'écrire tout simplement des commentaires. Je rendrais mon code encore plus clair ». A-t-il ajouté.

Il réalise aussi que l’utilisation des commentaires traduit l’incapacité du développeur à pouvoir montrer explicitement son intention dans le code.

« Quand j'ai lu le livre de l'oncle Bob, Clean Code, ma position s'est encore renforcée. Non seulement l'oncle Bob dit que nous devrions éviter les commentaires, il a dit - et montré - comment faire des commentaires, le plus souvent, indique un échec pour exprimer l'intention dans le code ».

Pour lui, un code avec des variables bien nommées est plus clair et communicatif qu’un « bon » code fortement commenté.

Pour le démontrer, il a utilisé un code réel à partir du framework .NET. Il s’est attaqué à une méthode à titre d’exemple qu’il a réécrite, en renommant les choses comme il se doit. Et le résultat, selon lui, est quelque chose de plus clair et plus propre.

Une autre raison pour laquelle il suggère encore d’éviter les commentaires, c’est que les codes sans commentaires sont plus faciles à maintenir.

Il a développé son point de vue dans un billet intitulé « Pourquoi les commentaires sont stupides, un exemple réel », sur le blog Simple Programmer.

Source : Simple Programmer

Et vous ?

Qu’en pensez-vous ?

Pourquoi devrait-on ou non ajouter des commentaires dans son code?

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

Avatar de Jbx 2.0b
Membre chevronné https://www.developpez.com
Le 15/04/2015 à 11:04
Sujet plusieurs fois abordé, et je suis toujours pas d'accord. On se doit d'écrire son code avec des noms de méthodes/classes/variables le plus clair possible, et très souvent ça se suffit à soi même. Parfait. Mais il restera des cas ou les commentaires sont un passage obligatoire.

Je pense que son exemple de refactoring est un mauvais exemple. Il ne met en jeu que des connaissances propres aux développeurs lambda. Le vocabulaire est connu de tous : path, string, split, directory, separator, slash... Il suffit effectivement d'écrire correctement (grammaticalement parlant) son code pour qu'on saisisse l'algorithme. Très bien.

Maintenant on ajoute des connaissances métiers pointues (propre à un secteur d'activité en particulier) et on saupoudre d'un bon vieux algo basé sur une belle formule mathématique (choisie parmi d'autres pour une obscure raison). Ça ne marche plus. Il va falloir commenter (parfois abondamment) si on veut se faire comprendre de l'utilisateur du service, ou du type qui va venir le maintenir. Voir même lui donner un lien vers une doc.
20  0 
Avatar de Excellion
Membre averti https://www.developpez.com
Le 15/04/2015 à 13:15
Que je sache l'un n'empêche pas l'autre.

C'est d'ailleurs souvent l'argument premier des débutants : ils ne documentent pas leur code, le nom de variables suffit.
6 mois après, quand on reprend les 1500 lignes que représentent l'unique méthode d'une classe, on pleure un peu. Beaucoup, même.
Surtout que les dénominations qui semblaient claires pour la personne à une époque le sont nettement moins pour une autre personne, quelques temps après.

Bien documenter son code (notamment les classes et les méthodes) permet de savoir d'un coup d'oeil ce que fait le code.
Bien nommer les choses permet de savoir à quoi elles servent, dans le détail.

En somme les deux sont importants, mais ça, il n'y a que l'expérience qui peut le démontrer...
10  0 
Avatar de yahiko
Rédacteur/Modérateur https://www.developpez.com
Le 15/04/2015 à 14:55
Si on se donne la peine de lire l'article original et la refactorisation de l'auteur, il n'est pas si évident que cela que le code remanié soit si clair par rapport au code de départ.
Remplacer une procédure, pas génialement écrite certes, mais qui est loin d'être indigeste, par l'usine à gaz qu'est sa classe avec toutes ses méthodes que l'auteur introduit dans son refactoring, juste pour séparer le nom d'un fichier de son répertoire... OMG...

Du coup, ça ne donne pas envie de croire l'auteur sur paroles.

Au niveau de l'argumentation assez fallacieuse, l'auteur tente de montrer que parce qu'il est possible d'écrire du code plus clair (aucun souci avec cette affirmation), alors les commentaires sont inutiles... C'est un peu comme mélanger les choux et les carottes. Avec ce genre de raisonnement on peut aussi dire que comme on peut bien commenter, il n'est pas nécessaire d'écrire du code clair. C'est absurde évidemment. Il faut à la fois écrire du code clair et bien commenter.

Les commentaires sont utiles à partir du moment où on travaille en équipe (et même pour soi-même les commentaires peuvent parfois sauver plusieurs heures). D'autres ont bien expliqué cet aspect ici avant moi, tant mieux. Les commentaires donne une vision plus large que le code. Pour schématiser, les commentaires doivent expliquer le pourquoi, alors que le code s'occupe du comment.

Aussi d'un point de vue plus pratique , les commentaires lorsqu'ils sont bien écrits permettent une lecture en diagonale sans avoir à se plonger dans le dur du code. Cela permet de gagner du temps dans la compréhension global d'une base de code.

Bref, j'ai quand même un peu peur que cette idée de ne pas commenter le code ne devienne tendance auprès de jeunes développeurs qui pourraient y voire l'opportunité de faire l'impasse ce qui est souvent vu comme un fardeau et une tâche ingrate.
10  1 
Avatar de dfiad77pro
Membre expérimenté https://www.developpez.com
Le 15/04/2015 à 11:00
En C# et Java je privilégie la documentation des méthodes et attributs même private.

Le but à atteindre est que les méthodes se comprennent d'elle-même. Les commentaires sont présents lors de l'implémentation d'un algo complexe. Mon entreprise a un WIKI auquel on peut mettre un liens dans le code avec une explication schématisée claire.

Le nommage est pour moi un des aspect les plus difficile de la programmation, d'autant plus qu'en français sans accent , c'est moche ( norme de mon entreprise, et généralement en C# on ne met pas d'accent dans les variables même si c'est autorisé).

Des fois je relis des vieux code VB6 et je vois qu'il y a 1000 lignes de commentaires avant de débuter le code ( historique de modifs des dev), ça fait pas propre.
9  1 
Avatar de micka132
Expert confirmé https://www.developpez.com
Le 15/04/2015 à 11:00
Je suis mitigé. Sur l'exemple qu'il donne autant à la lecture c'est plus concis, autant en cas de debug ça devient beaucoup plus embêtant puisqu'il faut faire beaucoup plus d'aller/retour entre toutes les méthodes qu'il créé.
Ensuite je ne suis pas forcement fan de multiplier des méthodes de quelques lignes qui ne servent que dans le contexte particulier d'une autre méthode. On arrive vite à des fichiers énormes et on perd rapidement en clarté globale.

Renommer les variables oui, remplacer tout par des méthodes bof, je ne parle même pas des nombreux cas où l'on doit ajouter un petit quelque chose qui fait que le nom que l'on a choisit n'est plus tout à fait juste...Et en cas d'oublie de refactoring du nom c'est bien pire qu'en cas d'oublie de modif de commentaire : soit on se fie au nom et c'est le drame, soit on "s'amuse" à naviguer vers chaque méthode pour vérifier qu'elle fait bien ce qu'elle dit.
7  0 
Avatar de Gulien
Membre habitué https://www.developpez.com
Le 15/04/2015 à 11:49
Le sujet a été maintes fois débattu,
C'est évident qu'une variable se nommant "ActionEcheanceButoirDate" sera plus facile à lire que "Date1" pour quelqu'un qui lirait le code pour la première fois
Après reste à savoir l'ordre dans lequel on place les noms qui composent la variable
"ActionDateEcheanceButoir" ou "ActionEcheanceButoirDate" (Les trie-t-on par type de variable ou concept métier ?), mais ça c'est un détail de règle de programmation.

Pareil pour les méthodes.

Néanmoins, à force d'essayer d'atteindre la perfection on en oublie les bonnes pratiques qui sont de faire une documentation (JavaDoc ou autre) de ses méthodes...
Et encore plus si on découpe le code en une infinité de petites miettes à usage unique.
Je suis d'accord sur le principe, mais il faut que ça soit fait de façon extrêmement rigoureuse et documenté.

Comment le nouvel arrivant va savoir qu'il existe telle fonction à tel endroit si ce n’est pas répertorié / documenté ? Et dans ce cas, oui on peut se passer des commentaires.

Bref je me méfie des jusqu'au-boutistes du "pas de commentaires", et concernant les variables bien nommées, il y a toujours une limite à expliquer un concept en un mot...
au lieu de ce commentaire, j'aurais pu écrire "DaccordMaisDocumentons", beaucoup de gens auraient compris, mais est-ce que ça aurait eu la même signification?
7  1 
Avatar de fredo38
Membre régulier https://www.developpez.com
Le 15/04/2015 à 11:43
Le mieux est parfois l'ennemi du bien. De mes 20 années d'expérience en SSII dont une grande partie de programmation j'arrive à cette, ma, conclusion :
Pour les puristes du coding et des langages qu'ils maîtrisent, le naming des procédures, fonctions et variables se suffit à lui-même.
Pour les autres, dont moi, il faut passer par une phase de dé-tricotage du code (90% du temps) afin de comprendre ce qu'il fait, avant de pouvoir intervenir (très souvent pour corriger une erreur non prévue au départ).
Je passe rapidement sur le fait que les langages ne sont pas en français, ni qu'un terme en xxx n'est pas exactement le même en yyy.
L'avantage de commenter son code dès le départ et surtout au cours de sa vie permet d'être clair sur ce que l'on attend du traitement et sur les modifications que l'on y a apportées.
Alors oui pour des commentaires (concis) ET des variables, procédures, fonctions,... qui disent ce qu'elles f(s)ont et qui font ce qu'elles disent.
5  0 
Avatar de watchinofoye
Membre habitué https://www.developpez.com
Le 15/04/2015 à 11:50
Qu’en pensez-vous ?
J'en pense que l'un n'empêche pas l'autre, voire qu'il vaut mieux adopter des noms explicites et clairs ET des commentaires clairs dans les cas où le code en lui-même a besoin d'explications sur son fonctionnement (de sorte à ne pas perdre de temps à se demander à quoi ça sert).

Concernant les noms, un truc que j'ai vu et qui m'a bien plu c'est l'habitude de nommer les types de données en fonction de l'unité. Par exemple (extrait des règles de codage de Médiane Système) :
Code : Sélectionner tout
1
2
3
4
5
6
7
8
9
10
dans un fichier.h regroupant les types :
typedef int pression_en_bar ; /* type entier- gamme 0 .. + 210 - unité : bar */
typedef int gain_mesure_pression; ; /* type entier- gamme 0 .. 10 - unité : sans */

dans un fichier regroupant des constantes :
const pression_en_bar offset = 2 ;
const gain_mesure_pression correction_gain = 10 ;

dans le fichier de la fonction :
consigne_pression = ( consigne - offset ) * ( pression_en_bar) correction_gain ;

À part ça, ça me fait toujours marrer de voir certains développeurs faire tout un pataquès, parfois plein de mauvaise foi, parce qu'ils trouvent que tel aspect de développement leur semble stupide et que tout le monde devrait faire comme eux alors qu'au final ce n'est que leur avis personnel.
5  0 
Avatar de Cédric Doucet
Membre à l'essai https://www.developpez.com
Le 24/04/2015 à 16:25
Bonjour,

c'est un faux problème et/ou une mauvaise exégèse des livres mentionnés.
Ces livres ne prônent pas du tout l'arrêt des commentaires.
Ils prônent l'arrêt des commentaires redondants et des commentaires palliatifs à l'aide d'un nommage correct des variables et fonctions.

Dans l'exemple suivant, le commentaire est redondant :
Code : Sélectionner tout
1
2
3
// return the size 
int size();
C'est typiquement le genre de commentaire qu'on peut trouver dans les codes auto-documentés à l'aide de générateurs comme doxygen, javadoc, docstring, etc.

Dans l'exemple ci-dessous, le commentaire est palliatif :
Code : Sélectionner tout
1
2
// print working directory
void pwd();
Il aurait été tout aussi efficace de supprimer le commentaire et de renommer la fonction :
Code : Sélectionner tout
1
2
void printWorkingDirectory();
De manière générale, il faut éviter les abréviations.
Toutefois, il existe des domaines dans lesquelles certaines abréviations sont consacrées.
Dans ces cas particuliers, tenter de mieux nommer la variable pourrait presque nuire à la lisibilité du code.
La manière dont on nomme les variables dépend du contexte.
Dans certains contextes, conserver le nom pwd plutôt que PrintWorkingDirectory pourrait se justifier.
Mais dans les deux cas, le commentaire reste redondant et inutile.

En dehors de ces commentaires, il en existe beaucoup d'autres qui sont utiles.
Par exemple, le commentaire ci-dessous :
Code : Sélectionner tout
1
2
3
4
5
// Warning: this singleton class is not designed to work in a concurrent programming environment 
class Singleton
{
   // implementation details
}
Bref, il n'a jamais été question de supprimer les commentaires.
Il s'agit de rendre les codes plus lisibles :
- en nommant mieux les variables et les fonctions
- en supprimant les commentaires inutiles qui nuisent à la lecture (parcours vertical des yeux)

L'idée fausse qu'il faut supprimer tous les commentaires est malheureusement propagée par certains acteurs de la mouvance agile qui retiennent uniquement que "la documentation c'est le code".
5  0 
Avatar de NSKis
En attente de confirmation mail https://www.developpez.com
Le 15/04/2015 à 13:02
Il faut les 2!!!

Quand vous avez du code qui voit passer plusieurs générations de développeurs, le nommage "futé" des variables n'est pas suffisant!!!

Le nom d'une variable aussi claire soit-elle n'indiquera jamais l'idée ou l'approche choisie par le précédent développeur pour implémenter une fonctionnalité
4  0 
Contacter le responsable de la rubrique Accueil

Partenaire : Hébergement Web