Discussion :

[martopioche]

D'une part, quand je fais une comparaison de code entre deux révisions SVN, le code n'est pas ouvert dans un IDE.
D'autre part, même avec un vrai IDE, rien n'est plus rapide qu'avoir directement le code sur place, sous les yeux.

Si sur le principe c'est vrai, dans le premier cas, tu organise ton code pour un cas particulier (comparaison d'historique) plutôt que pour un usage plus général (lecture du code). Simple stat : combien de fois un lecteur parcours un code vs compare des historiques ?

Pour le second, je ne suis pas convaincu : qu'apporte le code du filtre de mots sur le reste ?

Par exemple, cela peut arriver si la documentation technique ne précise pas sur quel critère le programme se base pour déterminer si un mot est injurieux voire ne précise pas que le programme filtre les mots injurieux.
Scénario possible : Un client se plaint qu'un certain mot ne soit pas pris en compte. Le help desk ne reproduit pas le problème en local et me le retransmet. Je découvre que le code appelle filterOffensiveWords() et je soupçonne cette fonction d'avoir filtré le mot chez le client mais pas chez moi. J'ai besoin de savoir comment elle marche. Je lis son code et je découvre que la liste des mots injurieux se base, entre autres, sur un fichier de préférences du client. Je complète alors des documentations dont celle destinée au help desk pour que, la prochaine fois, le personnel du help desk regarde dans le fichier de préférence du client avant de me retransmettre le problème.

Ce cas est plutôt un contre exemple… :p
Sur cette anecdote, tu est bien d'accord que ton process est d'écrire un test d'appel à filterOffensiveWords() avec le mot particulier et voir voir que ça marche chez toi, puis vérifier ce code et je ne vais pas paraphraser ce que tu a écris. Oui tu complète la documentation (pour moi ça commence par la fonction filterOffensiveWords() en ajoutant "filtre basé sur le fichier de préférences"), mais le découpage en fonction t'a permis de cibler plus rapidement le problème. D'ailleurs, si la doc de la fonction est déjà à jour, tu a demandé au helpdesk si ils ont vérifié ça avant même de tester…

Personnellement, quand j'écris un commentaire relatif à un ticket, je complète le ticket et j'y écrit "Voir les occurrences de XXXX (le numéro du ticket) dans le code". Du coup, il y a un léger espoir que celui qui aura corrigé le ticket mettra à jour le commentaire.
Sinon, si le commentaire n'a pas été mis à jour et que quelqu'un le lit, il se peut qu'il cherche à avoir plus d'informations en consultant le ticket puis découvre que le ticket est fermé. Alors, il devrait supprimer le commentaire.

"Personnellement", "espoir", "si", "il se peut", "il devra"…*Tu ne trouve pas que ça fait un peu trop pour espérer que ce soit fait ? De plus, c'est en contradiction avec ce que tu dis avant à propose de la rapidité d'avoir l'information. Car à nouveau :
- Si le ticket n'a aucun rapport avec ce bout de code (le ticket a une influence sur ce comportement mais ne le concerne pas directement), celui qui traite le ticket ne verra jamais ce commentaire
- Si le lecteur de ce code n'est pas concerné par un problème lié à la description du commentaire, il n'ira jamais voir le ticket…

Admet que ces deux cas sont des certitudes…

On dirait que je fais pareil que foetus.
Parfois, lors d'un développement, j'ai besoin d'avoir sous les yeux comment étaient certaines portions de code juste avant que je ne les modifie, sans perdre du temps à chercher la précédente version dans la dernière révision SVN. Alors, au lieu de supprimer tout de suite l'ancienne portion de code, je la mets en commentaires. Quand le développement est fini et qu'il semble bien marcher, je supprime le code mort avant le commit.

Ce que tu décris est différent de ce que j'ai compris de foetus. Faire évoluer du code en le réécrivant et pour ça commenter l'ancien le temps de la réécriture, je ne vois pas le problème, ça reste une action personnelle qui ne quitte pas la version locale et la publication est propre. Dans le cas de foetus, j'ai cru comprendre que ce code mort reste ad-vitam aeternam "au cas où"…

[martopioche]

Cela peut paraître à de la micro optimisation, mais c'est un code en retirant définitivement:

• Tous les debugs qui ne peuvent pas être désactivés et très souvent codés/ rajoutés à l'arrache.
• Tous les "fake", "stub", ou autres "test double" qui ne servent plus à rien.

Et même des fois, tu les as retirés (en cours de développement) mais il reste des initialisations seule/ des "include" par exemple que tu avais loupé (c'est pour cela que j'utilise un commentaire "// <- XXX" pour les marquer).

Je suis désolé mais il y a un truc que je ne comprends pas…*Celui qui a placé un debug sans prendre la peine de le rendre désactivable, selon quel principe mettrait-il un commentaire pour le désactivé, c'est contraire au principe LaRache ! Et je serai toujours émerveillé par la préférence de rajouter un commentaire plutôt que de mettre un temps à peine plus long "corriger" le code…

Et pour les "tests", "stubs" etc, pourquoi ne sont ils pas injectés par des modules dédiés eux-même dépendant de l'état du projet ? Sérieux, on est en 2017, on sait d'expérience que tout ce qui lors d'une livraison nécessite une intervention manuelle conduira inévitablement un moment ou un autre à livrer une version de dev…

[CaptainDangeax]

ça me rappelle mon stage de fins d'études à l'IUT, en 1990 : débugguer la ROM d'un terminal qui avait les caractéristiques suivantes : µC Intel 8031, connexion par boucle de courant RS485, Afficheur LCD 2x40 caractères, clavier alphanumérique, lecteur de badges magnétique, module PIO. Toutes les fonctions gérant les E/S fonctionnaient, mais pas l'ensemble du firmware... Le code assembleur était écrit sans commentaire et avec des fonctions au nom abscons, sans parler des variables : A1, A2, A3, à ne pas confondre avec les registres A, B, R0 à R7, DPTR, P2... Je ne connaissais même par l'existence du 8031, on n'avait vu que le 8085 (ancêtre du Z80) en cours. Merci l'éducation nationale de nous apprendre des processeurs démodés. Les 3 premiers jours, je les ai passé à isoler les fonctions et à commenter le code assembleur, sur un PC 286 en 80x25 EGA. La ROM une fois assemblé pesait 11kB, c'est gros pour du 8 bits... Jeune débutant à l'époque, j'aurais aimé des commentaires. Bon j'ai réussi la mission et j'ai eu mon DUT.
Maintenant, je nomme mes fonctions et mes variables avec des noms explicites, au moins quand elles servent au long du programme. i, j, k conviennent très bien pour des indices de boucle locaux à une fonction, on n'est pas dactylo non plus. Même si personne ne me relit, c'est plus facile même pour moi quand il faut reprendre le code plus tard.

[CodeurPlusPlus]

(...)Je cite des pratiques qui font consensus et ont fait leurs preuves. (...)

Tu as toujours raison, quoi. Exactement ce que je te reprochais.

[Bousk]

Sérieux, on est en 2017

Et ? T'as jamais vu du code vieux de plusieurs dizaines d'années ? Tu peux aller voir ton patron et dire "bon mec, notre code il marche mais il a 30 ans, faut le changer, on est en 2017 !" ? Et il accepte et est prêt à changer un truc qui marche sans broncher parce que tu lui montres un livre ?
Bienvenue dans le monde réel.

[transgohan]

Sérieux... Je travaille sur du matériel qui date d'avant ma naissance.
Tout refaire cela chiffre en milliards d'euros.
Je suis assez de l'avis des autres intervenants martopioche, soit tu troll soit tu ne sais absolument pas de quoi tu parles...
Tu cites un livre pour dire que tes propos ne viennent pas de ton expérience généralisée mais j'ai plutôt l'impression que tu n'as pas lu correctement ce dit livre et que tu généralises à tout va ce que tu en as compris...

Cela peut paraître à de la micro optimisation, mais c'est un code en retirant définitivement:

Tous les debugs qui ne peuvent pas être désactivés et très souvent codés/ rajoutés à l'arrache.
Tous les "fake", "stub", ou autres "test double" qui ne servent plus à rien.



Et même des fois, tu les as retirés (en cours de développement) mais il reste des initialisations seule/ des "include" par exemple que tu avais loupé (c'est pour cela que j'utilise un commentaire "// <- XXX" pour les marquer).

Ah oui j'avais pris l'habitude de faire ça aussi, c'est bien pratique quand on merge en branche d'intégration ou de livraison pour se rendre compte qu'il reste du debug.

[Shepard]

Par exemple, une requête SQL qui permet de récupérer le premier id non utilisé (pour remplir les trous)

Vade retro, Satanas !

[jopopmk]

@Pyramidev : très rapide, je vous laisse débattre ensuite

1. Le cas est intéressant, mais perso je passerai alors par une macro, pas une variable en rab.

2. La factorisation est évidemment de mise, toutefois je pourrais opter selon les cas pour des macro ou des inline.
Pour ce qui concerne la taille par contre, je m'en fous. Mon EDI sait collapse/expand les blocks et possède également une notion de "region".

On remarque déjà pour ces deux points que le billet n'a pas vraiment tort, on peut se passer de commentaire en faisant autrement.
Mais certainement pas en rajoutant des variables ou des fonctions, ou alors dans un langage qui n'en pâtirait pas.

4. Certaines fonctions n'ont pas besoin d'être en mode défensif, c'est même assez fréquent pour les fonctions internes utilisées en bout de pile.
Du coup je me vois mal coller un test qui sera toujours vrai pour ... quoi ?

En conclusion : je ne modifierai jamais le fonctionnement de mon code pour éviter des commentaires. Les macro dont je parle plus haut sont d'abord faites dans un but fonctionnel (var macro permettant d'avoir une même valeur de partout et facilement modifiable) et/ou pratique (fn macro m'évitant de réécrire 50x les 3 mêmes lignes).

Allez, moi je suis en kend dans pas longtemps, bonne discussion à tous

[Invité]

Commentaire != Documentation inline. Je me demande combien ce sont fais avoir...
Est-ce que dans l'article il est possible de faire une confusion à ce sujet? Ça mérite une relecture! Haha.

Trêve de troll, le code c'est aussi une histoire de gout. Certain vont extraire un bout de code pour en faire une méthode, d'autre non. Je pense que cela ne pose aucun problème en soit, l'ajout d'un commentaire (dans un cas comme dans l'autre) n'est peut être pas non plus nécessaire selon le contexte (en dehors de la doc inline).

[Pierre Fauconnier]

Quid du commentaire "inutile" qui permet d'autogénérer la doc?

[Programming-Z]

En générale, les commentaires ne sont pas nécessaires si on défini correctement les noms des variables et fonctions.

Quand on insère plus de ligne de commentaire que de code, c'est qu'il y a un problème quelque part (mentalement surement )

[Sodium]

J'essaye de passer le plus possible par des fonctions ou des variables temporaires au nom évocateur.
J'en utilise généralement quand l'utilité d'un bout de code n'est pas évidente, que ça soit pour moi-même ou pour d'autres personnes ayant éventuellement à le relire.
C'est là que l'on trouve les limites des outils tels que PHPMetrics qui donnent beaucoup d'information utiles mais ont la mauvaise idée d'évaluer l'accessibilité d'un code par le ratio commentaires / opérations.

À l'inverse, la personne avec qui je travaille ne juge utile ni de factoriser, ni de commenter son code, peu importe le nombre de milliers de lignes et le côté cryptique de celles-ci, ce qui devient rapidement ingérable.

[Bryce de Mouriès]

Faisons rapide et simple :

1. Introduire une variable explicative
Non, je vais pas rajouter une variable inutile.
Si vraiment on a besoin d'une explication alors un commentaire va très bien.

2. Extraire une méthode
Toujours non, je vais pas empiler des appels inutiles.
Si vraiment on a besoin d'une explication alors un commentaire va très bien.

3. Utiliser un nom d'identificateur plus descriptif
Là c'est assez évident. Maintenant il peut arriver qu'on se retrouve avec des noms sans fin, on peut alors contextualiser les variables avec un petit commentaire (dans l'exemple, en tête d'algo, indiquer "all sizes in pixels" ).

4. Ajouter un contrôle dans le cas où votre code a des hypothèses
Gné ? Faire du défensif pour économiser un commentaire ? Là je sais même pas quoi dire ...

Complètement d'accord avec toi jopopmk, je me faisais la même réflexion. Ecrire plus de code pour éviter de taper un commentaire ?!? Cela sera forcément moins clair car moins détaillé, et cela demande plus de travail. En plus si on est puriste ça dégrade infimement les perfs.

Je trouve que ça a très vite ses limites le beau code que l'on est sensé comprendre sans aucun commentaire, c'est assez subjectif, je préfère largement lire les commentaires jusqu'à trouver l'endroit qui m'intéresse plutôt que lire le code, lire le code c'est comme lire une langue étrangère, on aura beau la connaître il y a toujours un travail de traduction dans la tête. Alors que lire un texte se fait naturellement. Le premier exemple le montre très bien, avec commentaire on sait immédiatement que c'est l'application d'une réduction, il n'est même pas utile de lire le code.

Après on est jamais seul sur un projet (je considère que le moi du futur est une autre personne qui ne comprendra peut être pas ce que le moi du présent a bien pu avoir en tête quand il a écrit son code...).

[Sodium]

Complètement d'accord avec toi jopopmk, je me faisais la même réflexion. Ecrire plus de code pour éviter de taper un commentaire ?!? Cela sera forcément moins clair car moins détaillé, et cela demande plus de travail. En plus si on est puriste ça dégrade infimement les perfs.

Plus de code ? Non, car factoriser son code oblige à réfléchir à ce que l'on fait et généralement à le simplifier.
Moins clair car moins détaillé ? Absolument pas.
Plus de travail ? Encore une fois non, car un code moins complexes est plus facile à maintenir.
Dégrader les perfs ? Pratiquement tous les compileurs ou interpréteurs se foutent complètement de la façon dont est écrit le code et l'optimisent très bien, à moins bien sûr d'avoir fait n'importe quoi.

[Bryce de Mouriès]

Plus de code ? Non, car factoriser son code oblige à réfléchir à ce que l'on fait et généralement à le simplifier.
Moins clair car moins détaillé ? Absolument pas.
Plus de travail ? Encore une fois non, car un code moins complexes est plus facile à maintenir.
Dégrader les perfs ? Pratiquement tous les compileurs ou interpréteurs se foutent complètement de la façon dont est écrit le code et l'optimisent très bien, à moins bien sûr d'avoir fait n'importe quoi.

On le voit bien dans les 4 exemples, il y a plus de codes. Les IDE nous aide pas mal aujourd'hui, ça reste toujours plus long que d'écrire une phrase, la finesse du langage permet toujours d'être plus précis

Honnêtement tu trouves ça

Code :

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

1
2
3
4
price = numItems * itemPrice;
discount =
    min(5, numItems) * itemPrice * 0.1;
finalPrice = price - discount;

plus clair que ça ?

Code :

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

// Subtract discount from price.

Après je suis d'accord, ça n'est pas une raison pour écrire tout son code sur une ligne parce qu'on a mis un commentaire juste au dessus.
Ne tient pas compte de moins commentaire sur les perfs, c'était pour troller

[Cincinnatus]

1. Introduire une variable explicative
Non, je vais pas rajouter une variable inutile.
Si vraiment on a besoin d'une explication alors un commentaire va très bien.

Si une variable intermédiaire peut remplacer avantageusement un commentaire en détaillant une opération, pourquoi s'en passer ? De toutes façons, le compilateur optimisera ton code, si c'est ça qui bloque.

2. Extraire une méthode
Toujours non, je vais pas empiler des appels inutiles.
Si vraiment on a besoin d'une explication alors un commentaire va très bien.

Même chose, le compilateur peut réduire les appels s'il l'estime possible.

3. Utiliser un nom d'identificateur plus descriptif
Là c'est assez évident. Maintenant il peut arriver qu'on se retrouve avec des noms sans fin, on peut alors contextualiser les variables avec un petit commentaire (dans l'exemple, en tête d'algo, indiquer "all sizes in pixels" ).

Dans leur contexte, les noms sont rarement très longs. Je préfère des termes explicites, plus faciles à relire.

4. Ajouter un contrôle dans le cas où votre code a des hypothèses
Gné ? Faire du défensif pour économiser un commentaire ? Là je sais même pas quoi dire ...

Effectivement, les deux ne sont pas exclusifs. Le commentaire précise l'intention, le code valide les hypothèses.
Dans le cas repris ensuite d'un âge de capitaine, si une donnée à une étendue précise, pourquoi ne pas créer un type vérifiant les contraintes ?

Un type AgeDuCapitaine pourrait bloquer en cas d'âge trop bas ou trop élevé et documenterait parfaitement ces contraintes.
On pourrait aussi avoir en dérivés les types AgeDuCapitaineDePedalo et AgeDuCapitaineDeLongCourrier.

Pour ceux que ça intéresse, le langage ADA est à étudier...

[Cincinnatus]

..., la personne avec qui je travaille ne juge utile ni de factoriser, ni de commenter son code, peu importe le nombre de milliers de lignes et le côté cryptique de celles-ci, ce qui devient rapidement ingérable.

Bon courage... J'ai déjà eu à reprendre du code (PHP ) qui était de ce style. Fonctions dupliquées mais écrites différemment, conditions à rallonge simplifiées avec un peu de logique, ...

[martopioche]

Et ? T'as jamais vu du code vieux de plusieurs dizaines d'années ? Tu peux aller voir ton patron et dire "bon mec, notre code il marche mais il a 30 ans, faut le changer, on est en 2017 !" ? Et il accepte et est prêt à changer un truc qui marche sans broncher parce que tu lui montres un livre ?
Bienvenue dans le monde réel.

Mais quel est le rapport avec l'âge du code ? La question est une question sur la pratique actuelle. Foetus, qui est celui que je citais, rebondissait sur "j'écris…", pas "j'écrivais il y a 30 ans…". Parce que le code a 30 ans, les pratiques restent figées à il y a 30 ans ?

Et truc qui marche sans broncher…*Si par ce process, il livre avec du code de dev ou qu'après la livraison les devs ont du code de prod, on est bien d'accord que ce truc "ne marche pas", non ?

Tout refaire cela chiffre en milliards d'euros.
Je suis assez de l'avis des autres intervenants martopioche, soit tu troll soit tu ne sais absolument pas de quoi tu parles...

Sauf que ce n'est pas moi qui parle de tour refaire…

Tu cites un livre pour dire que tes propos ne viennent pas de ton expérience généralisée mais j'ai plutôt l'impression que tu n'as pas lu correctement ce dit livre et que tu généralises à tout va ce que tu en as compris...

Ok, tu en a l'impression, tu en a compris quoi toi ?

[martopioche]

Ecrire plus de code pour éviter de taper un commentaire ?!? Cela sera forcément moins clair car moins détaillé, et cela demande plus de travail.

Moins clair car moins détaillé ? Qu'est ce qui est un "détail" acceptable ? Et plus le commentaire est long, qui prend le temps de le lire ? Quand à plus de travail…*Quel est la quantité de travail nécessaire pour déterminer un nom de variable "parlant" vs formuler une explication compréhensible ?

Je trouve que ça a très vite ses limites le beau code que l'on est sensé comprendre sans aucun commentaire

On ne parle pas de "beau code" ni de code sans aucun commentaire.

je préfère largement lire les commentaires jusqu'à trouver l'endroit qui m'intéresse plutôt que lire le code, lire le code c'est comme lire une langue étrangère, on aura beau la connaître il y a toujours un travail de traduction dans la tête. Alors que lire un texte se fait naturellement. Le premier exemple le montre très bien, avec commentaire on sait immédiatement que c'est l'application d'une réduction, il n'est même pas utile de lire le code.

Sauf que cet exemple est un… exemple. Qui illustre un usage et qu'il n'est pas représentatif de la vie du code. Plus le commentaire (et plus généralement la documentation) est "grosse", mois elle est maintenue. Et personne ne peut "garantir" que le commentaire dans 10 modification décrira ce qui se passe en dessous. Alors, en plus de ton "travail de traduction", tu va le compléter avec un travail de compréhension de "mais quel rapport" ???

Edit (pour ne pas multiplier les interventions) : pour ton exemple de quel cas est le plus "clair", évidemment que pour un humain pour la simple lecture le commentaire est plus évidente, mais dans quel contexte parcours-tu le code ? Le commentaire décrira l'intention, la lecture du code montrera l'action. On n'écrit pas du code à but pédagogique (la plupart du temps) mais pour qu'il soit exécuté et maintenu, et pour la maintenance, va-tu te reposer sur l'intention ou sur l'implantation sachant à quel point tout ce qui relève de la documentation est maintenu ?

Après on est jamais seul sur un projet (je considère que le moi du futur est une autre personne qui ne comprendra peut être pas ce que le moi du présent a bien pu avoir en tête quand il a écrit son code...).

Exactement, et c'est avant tout pour ces cas là que ces principes de bonnes pratique ont émergés.

[Aizen64]

Pour ma part, hormis le fait d'être assez verbeux sur le nom des variables, j'ai tendance à faire 2 choses :
- documenter quand je l'estime nécéssaire, assez souvent en fait, d'autant plus quand je dois coder en dur certains id qui correspondent à des données en base,
- tout fichier/classe possède des docBloc, toutes les méthodes sans exception fournissent dans le docBlock le type, le nom de la variable et une description précise et ce même si nom de variable est assez explicite,
- tout paramètre de configuration est aussi documenté avec son type et une description, l'idée m'est venue en modifiant des fichiers de conf de SGBD,
- quand l'ordre de chargement de fichier n'est pas forcément évident, pour un framework et ces différents fichiers de config, l'ordre est fourni dans un commentaire en début de fichier

Oui c'est verbeux, et ça prend du temps à faire si on ne le fait pas dès le début mais par la suite, ça peut aider de nouveaux venus et les IDE aident pas mal pour récupérer ces docs automatiquement.