Etes vous pour ou contre les commentaires dans le code

[omarcisses]

Bonjour tout le monde,

Je suis actuellement en mission chez un client . A mon arrivée, j'ai vu un code assez verbeux , super mal codé (des map de map de map partout) , peu tester (12% de couverture de code), impossible à comprendre. J'ai posé la question à savoir pourquoi le code n'est pas commenté. A ma grande surprise on me réponds que le code doit s’auto-commenter et que si on met des commentaires ça veux dire qu'il y a un problème (a d'autre termes il n'est pas parlant). alors que moi j'ai toujours pensé que le code même si un code est parlant, les commentaires apporterais plus de visibilité. J'aimerais avoir votre avis.

[Jidefix]

Mon avis personnel rejoint en partie celui que tu as eu: il est inutile de commenter TECHNIQUEMENT un code. Dans ce que j'ai vu, ce sera alors des commentaires du genre

Code :

1
2
3
4
5
6
7
8
9
10
11
//Récupération de la connexion
Connection = ConnexionFactory.getConnexion();

//Exécution de la requête
request.execute();

//Initialisation de la liste des courses
List courses = new List();

etc...

qui sont juste redondants et n'apportent rien au développeur qui fait la relecture (pire: une méthode qui pourrait tenir sur une seule page va alors déborder!).

En revanche, il peut-être utile de commenter FONCTIONNELLEMENT le code, de manière à récapituler son UTILITE

Code :

1
2
3
4
5
6
//Calcul de la trajectoire de ma fusée
...

//Sauvegarde des paramètres
...

Du coup, la plupart du temps, la javadoc devrait suffire puisque dans un monde idéal, les méthodes devraient se découper en sous-méthodes.

Concrètement, qui n'a jamais écrit une méthode bien procédurale de 4 pages de long?


Bref, dire que le commentaire est inutile est un peu osé (et c'est prendre plusieurs générations de programmeurs pour des couillons). En revanche, le commentaire doit rester simple, et ne doit pas être une excuse pour coder comme un goret.

[Paul TOTH]

Envoyé par omarcisses

Bonjour tout le monde,

Je suis actuellement en mission chez un client . A mon arrivée, j'ai vu un code assez verbeux , super mal codé (des map de map de map partout) , peu tester (12% de couverture de code), impossible à comprendre. J'ai posé la question à savoir pourquoi le code n'est pas commenté. A ma grande surprise on me réponds que le code doit s’auto-commenter et que si on met des commentaires ça veux dire qu'il y a un problème (a d'autre termes il n'est pas parlant). alors que moi j'ai toujours pensé que le code même si un code est parlant, les commentaires apporterais plus de visibilité. J'aimerais avoir votre avis.

j'ai bossé dans une boîte où ils considéraient que la doc et le code ne doivent pas être mélangés...cela avait pour effet d'avoir une doc jamais mise à jour et sans rapport avec le code

un de mes clients réclame une entête PHPDOC sur chaque fonction PHP codée...je trouve ça d'autant plus dommage que PHP est interprété et que tout cela est lu à chaque fois.

Maintenant un code comme tu le décrit est souvent le fruit de plusieurs années de développement par des développeurs qui se sont succédés sans se rencontrer ou sans avoir le temps de s'expliquer. Du coup plus personne n'ose toucher à rien de perd que ça s'effondre...et chaque modification ne fait qu'alourdir l'édifice La pire étant quand on te demande de réaliser une documentation du produit d'après ses sources

[sevyc64]

Cela dépend aussi des langages utilisés.

Il est vrai que les langages actuels, évolués, souvent Objet sont relativement parlant, pour peu que les noms de variables et méthodes soient judicieusement choisis. Les commentaires "techniques", comme dit Jidefix, sont bien souvent redondant avec le code et inutiles.

Dans des langages plus anciens, je pense notamment à certains ancien Basic, les commentaires sont les bienvenus, le langage lui-même n'étant pas toujours très parlant.


N'oubliez pas, les bonnes pratiques, c'est en gros 10% de commentaires, soit environ (pour faire simple) 1 ligne de commentaire pour 10 lignes de code.
3 lignes de commentaires en début de méthode pour expliquer succinctement, la fonctionnalité et le fonctionnement, ça fait une méthode à 30 lignes de code, soit grosso-modo, la taille maxi à essayer de ne pas dépasser.
On est dans les clous

[transgohan]

J'aurais tendance à dire que ne pas commenter c'est mal.
Le code se suffit à lui même ? Vous avez déjà vu des codes français ??
On peut interpréter de trente-six façons différentes (j'entends par là supposer sur le code sans lire les 3000 lignes de code) des fois tellement notre langue est riche et compliquée.

Donc avoir du code plus des commentaires associés cela permet d'avoir en quelque sorte deux visions afin de converger correctement.

[sybil]

il devrait exister du code en francais:

Code :

1
2
3
4
5
6
7
8
9
si(a==b){

 c=k;

}
sinon{
 allez_a M;

}

Code :

1
2
3
4
5
6
7
8
9
10
11
12
int i=0;
int ar[10];

int *ip;
ip=&ar[0]; // or ip=ar;

faire{
    i++;
*ip++ = 19;

}pendant_que(i<10);
imprimer_f("%i\n", ar[8]);

[sevyc64]

Envoyé par sybil

il devrait exister du code en francais:

Ça s'appelle Windev et son petit frère Webdev, édité par PCSoft.

Et bien que ce langage soit très décrié et très mal jugé par les développeurs en général, on trouve de plus en plus de logiciels commerciaux développés avec

[Paul TOTH]

Envoyé par sevyc64

Ça s'appelle Windev et son petit frère Webdev, édité par PCSoft.

Et bien que ce langage soit très décrié et très mal jugé par les développeurs en général, on trouve de plus en plus de logiciels commerciaux développés avec

PCSoft propose des produits permettant de développer rapidement et facilement des applications...ça explique la présence de celles-ci. Maintenant avec ce genre de produit - Lotus Notes dans un autre genre en est un bel exemple - il ne faut pas sortir de la philosophie du produit sous peine de tomber dans des problèmes insolubles et des bugs inattendus. Donc ce qui n'est pas prévu par le produit, on ne le fait pas même si c'est un vrai besoin ... exemple: les listes dynamiques n'existent pas sous Lotus Notes, les critères de sélection d'une liste sont figés; seule solution : utiliser le moteur de recherche documentaire intégré au produit.

[_skip]

Envoyé par Paul TOTH

PCSoft propose des produits permettant de développer rapidement et facilement des applications...ça explique la présence de celles-ci. Maintenant avec ce genre de produit - Lotus Notes dans un autre genre en est un bel exemple - il ne faut pas sortir de la philosophie du produit sous peine de tomber dans des problèmes insolubles et des bugs inattendus. Donc ce qui n'est pas prévu par le produit, on ne le fait pas même si c'est un vrai besoin ... exemple: les listes dynamiques n'existent pas sous Lotus Notes, les critères de sélection d'une liste sont figés; seule solution : utiliser le moteur de recherche documentaire intégré au produit.

C'est en fait le problème de tout outil ou framework qui fournit beaucoup d'automatisme et d'abstraction. Ce n'est pas un secret, plus ça fait de la magie, plus ça risque de poser des problèmes lorsqu'il devient nécessaire de contrôler finement les choses.

Après est-ce qu'on peut vivre avec et profiter de la productivité? Ou est-ce que finalement on perd les avantages parce qu'on est sans arrêt à devoir chercher des workarounds?

[el_slapper]

Pour revenir au sujet initial, voici un code COBOL que j'ai écrit il y a quelques années - lors d'une refonte sans specs, après la détermination du type de paiement :

Code :

1
2
3
4
5
     IF   TYPE-PAIEMENT-TIP
      AND MONTANT-PAIEMENT >= 100000000
        SET TYPE-PAIEMENT-CHEQUE TO TRUE
     END-IF
    .

Je pense que n'importe qui, même ne connaissant pas le cobol, comprendra qu'à partir d'une certaine somme, un paiement TIP est remplaçé par un paiement chèque.

Par contre, ce que ça ne dit pas, c'est le POURQUOI. Que je n'avais pas en commentaire dans le code original. Et que nous avons mis beaucoup de temps à comprendre; Voici donc le code final :

Code :

1
2
3
4
5
6
7
8
9
*    Le Préimprimé pour les TIP ne contient que 6 caractères
*    avant la virgule. Si le montant dépasse 1 million, on est obligé d'utiliser
*    un paiement par chèque
     IF   TYPE-PAIEMENT-TIP
      AND MONTANT-PAIEMENT >= 100000000
        SET TYPE-PAIEMENT-CHEQUE TO TRUE
     END-IF
    .

Et là, on sait aussi POURQUOI il y a ce truc étrange.....

Donc, je pense que les collègues du posteur initial ont à la fois raison et tort. Raison, parceque le code doit être compréhensible sans commentaire. Tort, parceque comprendre le code ne suffit pas. Là, j'avais un vieux nanard qui faisait pareil(en beaucoup moins lisible, mais je l'ai compris), mais impossible de savoir pourquoi il y avait cette verrue(et les métiers ne comprenaient pas non plus). Pourtant, elle était, et reste, indispensable.

[Barsy]

Je trouve très utile les commentaires en début de méthode qui sont lus par l’auto-complétion (ça dépend de l'IDE et du langage). C'est le minimum d'expliquer ce que fait une méthode.

Après, sans chercher à faire des stats (genre il faut 10%), un bon commentaire doit pouvoir expliquer en quelques mots le fonctionnement d'une partie d'un code. Trop de commentaire rend le code illisible, mais le manque de commentaire peut faire perdre du temps au développeur qui le reprend.

[ymoreau]

Envoyé par sevyc64

Cela dépend aussi des langages utilisés.

Je pense aussi. Personnellement je ne commente presque pas du code C++/Qt parce qu'avec des noms explicites (variables et fonctions) on comprend bien ce qui se passe, et la doc des fonctions (type doxygen) suffit à préciser l'objectif général du code.
Le ruby est particulièrement clair à lire également, quand on s'est habitué à sa syntaxe.

Après il arrive ponctuellement qu'on fasse un truc bizarre pour optimiser ou autre, et là il est utile de préciser pourquoi avec un petit commentaire. Mais bon c'est peut être quelques lignes sur un projet entier.

Concernant les maps de maps, je fais presque toujours des typedef avec un nom explicite.

[omarcisses]

je suis complétement d'accord avec Jidefix car y a des commentaires qui ne servent a rien. Par compte je pense que si on a un fonctionnel trés riche avec un code dont tous les développeurs se plaignent (par exemple j'ai modifié un css et je me suis tapé un bugs fonctionnel, injection des formulaires dans les services, une utilisations complément décalée de seam etc. ) on peut pour ne pas utiliser "doit" commenter les fonctionnalités complexes afin que les gens qui hérite du code puisse comprendre.

[DevTroglodyte]

Envoyé par omarcisses

Bonjour tout le monde,

Je suis actuellement en mission chez un client . A mon arrivée, j'ai vu un code assez verbeux , super mal codé (des map de map de map partout) , peu tester (12% de couverture de code), impossible à comprendre. J'ai posé la question à savoir pourquoi le code n'est pas commenté. A ma grande surprise on me réponds que le code doit s’auto-commenter et que si on met des commentaires ça veux dire qu'il y a un problème (a d'autre termes il n'est pas parlant). alors que moi j'ai toujours pensé que le code même si un code est parlant, les commentaires apporterais plus de visibilité. J'aimerais avoir votre avis.

Commenter le code fait partie de la "charte" de développement de ma boite : vu comment les programmes plus anciens ont été codés (comme des bourrins, et surtout JAMAIS commentés correctement), il a été mis en place sur l'intranet une charte de dev. afin que tous les programmes correspondent au même schéma, pour que tout soit maintenable et évolutif, et surtout commenté.

Après, on est sensé faire ces commentaires de manière utile : pas de commentaires de trucs évidents, pas de code en commentaire, javadoc à jour et correctement référencée, etc.

[omarcisses]

Envoyé par DevTroglodyte

Commenter le code fait partie de la "charte" de développement de ma boite : vu comment les programmes plus anciens ont été codés (comme des bourrins, et surtout JAMAIS commentés correctement), il a été mis en place sur l'intranet une charte de dev. afin que tous les programmes correspondent au même schéma, pour que tout soit maintenable et évolutif, et surtout commenté.

Après, on est sensé faire ces commentaires de manière utile : pas de commentaires de trucs évidents, pas de code en commentaire, javadoc à jour et correctement référencée, etc.

Je suis d'accord de ne pas faire des commentaires pour la beauté mais être aussi réfractaire au commentaire d'autant plus on a des methodes qui font plus de 300 lignes imcomphrensible et des map de map de map bref c'est l'enfer.

[ymoreau]

Envoyé par omarcisses

être aussi réfractaire au commentaire d'autant plus on a des methodes qui font plus de 300 lignes imcomphrensible et des map de map de map bref c'est l'enfer.

Ce que tout le monde dit c'est qu'il vaut mieux partir sur un code clair et bien découpé sans commentaire. Après une fois que le mal est fait, il me semblerait plus judicieux de factoriser le code pour le rendre lisible que commenter la bouillie existante pour tenter de la rendre compréhensible.

Ce que je veux dire c'est que quelqu'un qui va coder n'importe comment, il vaudrait mieux lui apprendre à bien coder plutôt que lui dire "dans ton cas il faut tout commenter". Un code illisible n'est pas une "raison" pour mettre plus de commentaire, mais plutôt un problème à la base.

[Paul TOTH]

Quand on manipule des objets DOM en Javascript, les commentaires sont aussi les bien venus

Code :

1
2
3
4
5
6
function updateItems(sender) {
  var tr = sender.parentNode.parentNode;
  tr.children[2].className = 'active';
  tr.children[4].children[2].className = 'off';
}

[Jidefix]

Faut dire aussi que du code javascript sera par définition bordélique et non explicite

Blague à part, c'est vrai que j'ai fait une fixette sur les langage objets, mais ça dépend énormément du langage et de ce qu'on en fait...
Le problème du javascript, c'est que généralement, on bidouille jusqu'à ce que ça marche et-la-on-y-touche-surtout-plus-malheureux! Et du coup c'est incommentable puisqu'on ne comprend même pas ce qu'on vient d'écrire.
Du coup le code commenté est aussi le plus évident

PS: mais je fais des efforts en javascript!

[omarcisses]

Envoyé par ymoreau

Ce que tout le monde dit c'est qu'il vaut mieux partir sur un code clair et bien découpé sans commentaire. Après une fois que le mal est fait, il me semblerait plus judicieux de factoriser le code pour le rendre lisible que commenter la bouillie existante pour tenter de la rendre compréhensible.

Ce que je veux dire c'est que quelqu'un qui va coder n'importe comment, il vaudrait mieux lui apprendre à bien coder plutôt que lui dire "dans ton cas il faut tout commenter". Un code illisible n'est pas une "raison" pour mettre plus de commentaire, mais plutôt un problème à la base.

je suis d'accord pour dire que y a un vrai problème de base mais quand en plus tu as un métier aussi complexe que l'achat et vente en bourse avec des formule partout je pense que les commentaires sont les bienvenues. Dans mon ancienne mission, on avait mis en place des règles afin que le code sois le plus lisible possible car il ne faut pas oublier qu'on ne code pas que sois. Et que les autres peuvent ne pas avoir la même logique que moi. Quand je code y a des chose que je ne commente pas par compte quand il s'agit d'un réel besoin fonctionnel avec des spécificités complexes je commente afin de rendre le code le plus compréhensible possible

[ymoreau]

Dans mes propos je ne compte pas la doc technique comme du commentaire, sinon bien évidemment il faut écrire quel est le but global des fonctions (encore que pour une partie d'entre elles le nom est souvent suffisant). Toujours dans le cadre du développement orienté objet.

Ça été dit au dessus, il y a des cas où il faut des commentaires. Ce que je voulais dire c'est que ça doit rester des exceptions et pas des habitudes.