Etes vous pour ou contre les commentaires dans le code

[omarcisses]

Envoyé par 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.

je suis d'accord avec toi ce qui me surprend c'est ce que je disais au début interdire les commentaires. C'est pourquoi j'avais ouvert le sujet car j'aimerais avoir d'autre avis.

[Bousk]

Interdire tous commentaires n'a pas plus de sens et n'est pas plus intelligent que de vouloir tout commenter.

Le meilleur commentaire, c'est bien sur le code lui-même, à condition qu'il soit bien écrit, que les noms de variables soient correctement choisies, que tout le monde comprenne ce choix et s'y tienne.
Tout simplement parce que le code sera finalement le seul commentaire toujours à jour.

Quoi de plus chiant que de mettre à jour le commentaire d'un code qu'on vient de mettre à jour ?

Pour ma part, je me contente de
- le header de la fonction en doxygen
- quelques commentaires au milieu, commentaires purement fonctionnels en général

[ymoreau]

Tout à fait, une interdiction pure et simple des commentaires me parait totalement absurde. Par contre encourager à un code clair et déconseiller les commentaires c'est différent, on laisse le choix au programmeur de faire ce qui est pertinent selon le contexte, c'est juste une "politique" à suivre. Mais tu n'as pas parlé d'interdiction formelle au début du sujet.

[Paul TOTH]

ne pas oublier qu'avec le temps on code différemment...mieux dans le meilleur des cas et quand on reprend son propre code 10 ans plus tard, il arrive qu'on trouve des horreurs ou des choses assez tordues dont la logique ne saute pas aux yeux. C'est d'autant plus vrai que 10 ans plus tard, toute la subtilité de la problématique n'est plus en tête (que ce soit le protocole utilisé, la structure de la bdd, le format de fichier etc...).

[Bktero]

Envoyé par Jidefix

Mon avis personnel rejoint en partie celui que tu as eu: il est inutile de commenter TECHNIQUEMENT un code.

[...]

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

Je partage cet avis, comme plein de gens, mais je n'y adhère pas totalement. Les exemples montrés étaient caricaturaux, bien que j'ai encore tendance à écrire ce genre de commentaires. Sur le coup, ça peut paraitre bête mais c'est tellement plus simple à relire quelques mois ou années plus tard. Comme le dit très justement Paul Toth :

ne pas oublier qu'avec le temps on code différemment...mieux dans le meilleur des cas et quand on reprend son propre code 10 ans plus tard, il arrive qu'on trouve des horreurs ou des choses assez tordues dont la logique ne saute pas aux yeux. C'est d'autant plus vrai que 10 ans plus tard, toute la subtilité de la problématique n'est plus en tête (que ce soit le protocole utilisé, la structure de la bdd, le format de fichier etc...).

De plus, cela sous-entend qu'un code est toujours techniquement compréhensible, avec des méthodes et des variables aux noms tellement beaux et adaptés que les commentaires copient ces noms de variables et de méthodes.

Mais des fois, commentez techniquement le code quand il y a des ruses de sioux ou des codes ésotériques tels que :

Code :

1
2
3
4
5
6
7
8
9
void *malloc(int s)
{
  void *p ;
  s += sizeof(int) ;
  s = (s & 0xF) ?  (s & ~0xF)+ 0x10 : s ;
  p = (s > 512) ? big_Malloc(s) : small_Malloc(s) ;
  *((int*)p)++ = s ;
  return p ;
}

Les adeptes du K&R apprécieront le style ^^

[sevyc64]

Envoyé par Paul TOTH

ne pas oublier qu'avec le temps on code différemment...mieux dans le meilleur des cas et quand on reprend son propre code 10 ans plus tard, il arrive qu'on trouve des horreurs ou des choses assez tordues dont la logique ne saute pas aux yeux. C'est d'autant plus vrai que 10 ans plus tard, toute la subtilité de la problématique n'est plus en tête (que ce soit le protocole utilisé, la structure de la bdd, le format de fichier etc...).

Pas besoin de 10 ans, il suffit de 6 mois, et 2 ou 3 projets assez ardus ou mal géré entre-temps

[Paul TOTH]

tient un autre cas ou le commentaire est bienvenu.

Je viens de tomber sur un bug IE9 totalement hallucinant...et comme je ne suis pas le premier j'ai trouvé une page qui montre le bug est le corrige.

je vais donc une fois de plus ajouter un commentaire du type <!-- corrige un bug IE - NE PAS SUPPRIMER -->

[gcorbineau]

Les commentaire en début de méthode pour moi sont indispensables, ça permet la description de la méthode, et des paramètres. Après dans la méthode, tous dépendant de la complexité de celle ci, mais il faut rester dans la limite du raisonnable et ne pas avoir plus de ligne de commentaire que de ligne de code!

[deathness]

Envoyé par gcorbineau

Les commentaire en début de méthode pour moi sont indispensables, ça permet la description de la méthode, et des paramètres. Après dans la méthode, tous dépendant de la complexité de celle ci, mais il faut rester dans la limite du raisonnable et ne pas avoir plus de ligne de commentaire que de ligne de code!

Tout est une question de contexte surtout. Plutot que de me demander ça je me demande plutot:
Est ce que le code va durer? va être repris? évoluer?
Combien de personne vont devoir s'en servir?
Etc...

Et en fonction de ça je commente les entetes, l'intérieur ou une doc pour expliquer l'archi général.

[Deca31]

Pour ma part, je pense que la proportion de commentaires est liée au langage mais aussi au contexte.
On ne peut pas comparer les conditions de maintenabilité de la même façon en gestion d'incident planifiée et en stress avec une obligation de résultat.
Dans ce deuxième cas avoir des commentaires inclus dans le programme aide certainement à répondre plus rapidement et plus surement.

Sur des langages non objets j'applique un ratio de 20% de commentaires en moyenne et je ne suis pas sur d'être dans le cadre de la norme ISO. Mais je suis plutôt à 5% sur du C# .

[BenoitM]

en C# par odre d'importance
1) Commenter les fonctions
2) Utiliser les regions pour découper les classes (attributs, propriété,methodes, implémentation d'interface)
3) Utiliser les regions pour regrouper plusieurs fonctions
4) Expliquer le pourquoi on fait certainnes actions en cas de nécessiter
5) Utilisation des régions pour découper certaines fonctions trop longue si on a pas eu le courage de les découper en plus petites

[Gecko]

Personnellement mes codes sont très verbeux, c'est tip top pour s'y retrouver, par contre le code en prod ne contiens pas un seul commentaire.

Je minimise les sources au maximum ce qui rend le code illisible mais plus réactif.

[sevyc64]

Envoyé par Gecko

Personnellement mes codes sont très verbeux, c'est tip top pour s'y retrouver, par contre le code en prod ne contiens pas un seul commentaire.

Je minimise les sources au maximum ce qui rend le code illisible mais plus réactif.

Sauf sur d'ancien langages purrement interprétés, les commentaires n'ont aucune influence sur la réactivité du code, ils sont supprimés à la compilation du logiciel (si tant est que l'on compile en mode Release et non pas en mode Debug)

[omarcisses]

Envoyé par Gecko

Personnellement mes codes sont très verbeux, c'est tip top pour s'y retrouver, par contre le code en prod ne contiens pas un seul commentaire.

Je minimise les sources au maximum ce qui rend le code illisible mais plus réactif.

Je si je comprends bien au moment de mettre en prod tu fait un revu de ton code en supprimant tous les commentaires. Je trouve ca un peu bizarre car si on raisonne sur la taille du projet je ne pense pas que les commentaires augmentent plus 500 Mo de la taille de ton projet. Pour la compilation et l'exécution, les commentaires ne sont pas pris en charge c'est pourquoi je trouve bizarre de supprimer les commentaire pour la mis en prod

[seeme]

Je rajoute ma petite expérience.

Boite de JV, solution maison (C++). Au début je mettais des petits bout de commentaire en tête de blocs pour expliciter ce que je faisais (//Check the main character's inventory.." -- Bloc d'une 20aine de ligne)

On m'a précisé que c'était inutile. Sauf cas particulier (astuce, dépendance qui impliques des choses "bizarres"..), le code doit être suffisamment clair pour être compréhensible: "Le code est sa propre documentation".

Si le code nécessite des commentaires toutes les 2 lignes, c'est qu'il n'est pas assez clair, que la fonction fait trop de chose, que les variables n'ont pas des noms assez explicites etc..

[deathness]

Envoyé par seeme

Je rajoute ma petite expérience.

Boite de JV, solution maison (C++). Au début je mettais des petits bout de commentaire en tête de blocs pour expliciter ce que je faisais (//Check the main character's inventory.." -- Bloc d'une 20aine de ligne)

On m'a précisé que c'était inutile. Sauf cas particulier (astuce, dépendance qui impliques des choses "bizarres"..), le code doit être suffisamment clair pour être compréhensible: "Le code est sa propre documentation".

Si le code nécessite des commentaires toutes les 2 lignes, c'est qu'il n'est pas assez clair, que la fonction fait trop de chose, que les variables n'ont pas des noms assez explicites etc..

C'est plutôt vrai. Mais encore faut-il avoir a coté une spec qui t'explique un peu l'ensemble, qui en gros te dessine l'archi général avec le but final.

[sybil]

La question ne se pose pas, les commentaires sont necessaires.

[Paul TOTH]

Envoyé par sybil

La question ne se pose pas, les commentaires sont necessaires.

sans commentaire.

[omarcisses]

Envoyé par sybil

La question ne se pose pas, les commentaires sont necessaires.

Heureusement qu'on fait un boulot ou rien n'est dogmatique. Tout dépend du contexte j'irais pas jusqu’à interdire les commentaires mais non plus dire qu'elles sont obligatoires.

[gangsoleil]

Envoyé par seeme

Sauf cas particulier (astuce, dépendance qui impliques des choses "bizarres"..), le code doit être suffisamment clair pour être compréhensible: "Le code est sa propre documentation".

Si le code nécessite des commentaires toutes les 2 lignes, c'est qu'il n'est pas assez clair, que la fonction fait trop de chose, que les variables n'ont pas des noms assez explicites etc..

Envoyé par omarcisses

Tout dépend du contexte j'irais pas jusqu’à interdire les commentaires mais non plus dire qu'elles sont obligatoires.

Et pourtant...

Qu'est-ce qui va plus vite ? Lire une phrase explicite, ou bien un code de 15 lignes explicite ?

Ex :

Code :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
/* Did the read went fine ? */
if (return_code == MY_RETURN_KO)
{
    bla bla
    bla bla
  
    appel de fonction de remplacement
   
    if (appel a merde la aussi)
    {
            bla bla erreur
            bla bla
    }

   fin du bla bla
}

Par ailleurs, dans les editeurs de code qui permettent de replier des parties de code, tu vois le commentaire, le if, et c'est tout. Tu n'as donc pas a deplier le code pour savoir ce qui est fait dedans.