[migration] [suggestion] nettoyage code commenté

[sly]

Dans la version de développement, mais aussi (dans une moindre mesure) celle de prod, on trouve beaucoup de code commenté, de fichiers de tests et de truc qu'on sait plus au final si ça va servir, si ça sert encore ou autre.

Perso, je trouve que ça brouille un peu la lecture du code et que ça serait finalement plus lisible s'il ne restait en commentaire que les "vrais" commentaires avec du français qui explique pourquoi ci ou ça.

Sachant que maintenant on a git pour s'occuper de tout l'historique de chaque fichier et qu'on peut par exemple retrouver l'historique par :
git log -p modeles/fonctions_nouvelles.php
ou sur :
https://github.com/sletuffe/www.refuges ... velles.php

Je propose, de se rapprocher d'une version ou "tout sert" (ou enfin, disons, presque tout) et donc ne pas hésiter à faire violence du genre :
"Tiens, mais ce bout de code n'est jamais appelé ? -> zou on le vire"
S'il s'avère qu'on s'est trompé, on le retrouvera dans l'historique.

Votre avis ? je me lance dans le ménage ?

[Dominique]

Entièrement d'accord
J'avais fait quelques passes de grep sur chaque nom de fonction quand je suis passé à OL
Il faudrait le refaire: virer toute fonction variable qui n'est pas citée dans le source

Exception: j'ai laissé quelques //TODO dans le code (je ne suis pas le seul). A moins que l'idée soit obsolète, on pourrait les y laisser ?

De même : l'historique de début de fichier: quel est l'intérêt de se rappeler que XXX à fait telle modif en 2008 ?
Signaler les modifs récentes permet de demander au cas ou le code serait instable, mais avec GIT, ça n'a même plus d'intérêt

[sly]

virer toute fonction variable qui n'est pas citée dans le source

Je ne suis pas sûr de comprendre cette phrase ?

Exception: j'ai laissé quelques //TODO dans le code (je ne suis pas le seul). A moins que l'idée soit obsolète, on pourrait les y laisser ?

Si si, on les laisse, moi j'utilise soit TODO soit FIXME. C'est même super utile pour repérer les coins "délicat" ou "à l'arrache" ou "peut mieux faire"
Mais ça, c'est du bon commentaire utile, pas comme :
// print ($debug);
qui l'est quand même moins.

De même : l'historique de début de fichier: quel est l'intérêt de se rappeler que XXX à fait telle modif en 2008 ?
Signaler les modifs récentes permet de demander au cas ou le code serait instable, mais avec GIT, ça n'a même plus d'intérêt

Je suis entièrement d'accord. Ça fait des en-tête de fichier trop lourd, que je fini par ne plus lire.
En rester à l'essentiel : à quoi sert ce fichier, qu'est-ce qu'on trouve "en gros" dedans. Le reste ayant tout intérêt à être en commentaire, en français expliquant les choses en début de fonction, en milieu de code zarbi.

[Dominique]

virer toute fonction variable qui n'est pas citée dans le source

Je ne suis pas sûr de comprendre cette phrase ?

Utilisée (dans aucun fichier): grep nom .../*.*

... pas comme :
// print ($debug);
qui l'est quand même moins.

Ha oui, ça: poubelle (c'était pour debugger un jour et on peut le remettre quand on veux

[yip]

Je suis daccord aussi pour :

virer les commentaires foireux (j'ai bien doublé leurs nombre recemment, temporairement)

virer les fonctions inutiles

virer l'historique

garder les FIXME et TODO, mais aussi les commentaires pertinents sur les points chauds ,
On garde aussi les commentaires à chaque début de fonction pour expliquer les INPUT et OUTPUT de la fonction ? des fois c'est pas évident

[sly]

Je suis daccord aussi pour :

virer les commentaires foireux (j'ai bien doublé leurs nombre recemment, temporairement)

virer les fonctions inutiles

virer l'historique

garder les FIXME et TODO, mais aussi les commentaires pertinents sur les points chauds ,

ok donc, j'ai pris un peu d'avance et à chaque fois que je rend compatible avec PG, j'en profite pour faire le ménage.

On garde aussi les commentaires à chaque début de fonction pour expliquer les INPUT et OUTPUT de la fonction ? des fois c'est pas évident

Je propose que oui, certaines que j'ai écrites sont vraiment complexes par ce qu'elles prennent en entrée et ce qu'elle recrache en sortie, donc un exemple de l'objet (qui s'apparente plus à un tableau) récupéré en entrée et de celui renvoyé en sortie me semble un plus pour mieux y comprendre.

[Dominique]

On garde aussi les commentaires à chaque début de fonction pour expliquer les INPUT et OUTPUT de la fonction ? des fois c'est pas évident

A voir au cas par cas. Il y a des fois où ça vaut le coup de commenter un peu