À lier aux autres règles : bien sûr que tu ne mets pas de commentaire si ça n'apporte rien ; mais souvent la correction d'un bogue va réécrire un bout de code d'une façon moins triviale qu'il faut expliquer en commentaire pour éviter que quelqu'un réintroduise le bogue subtil en simplifiant le code plus tard.
“It is seldom that liberty of any kind is lost all at once.” ― David Hume
souvent la correction d'un bogue va réécrire un bout de code d'une façon moins triviale qu'il faut expliquer en commentaire pour éviter que quelqu'un réintroduise le bogue subtil en simplifiant le code plus tard.
Sans considération sur la trivialité ou non d'une réécriture, la simple notification de la correction d'un bug invite à consulter l'historique (qui en général va contenir des détails sur le bug dont l'ancienne implémentation). C'est bien éviter sa réintroduction qu'on cherche à éviter, donc autant avoir ce qui ne marche pas "sous le coude".
Même sans explication, l'information est mise à disposition pour celui qui souhaite creuser les détails (tout comme une référence lors d'un copier/coller).
J'ajouterais que dans certaines boites, la consultation de l'historique est une pratique digne d'un rituel satanique réservé au praticien des arcanes dont l'âme a été morcelée afin de pouvoir la revendre a plusieurs entités.
Petite anecdote relativement liée, je suis d'ailleurs un jour tombé dans une équipe d'ingénieurs qui m'ont mis en garde contre l'utilisation du bouton "Blame" de jira, ne voulant pas attirer d'ennui au développeur ayant fait le commit… Des gens très compétents pourtant. Je garderai toujours un doute sur le fait qu'ils étaient sérieux.
À priori j'écris plutôt un test. C'est plus vivant et ça documente mieux je trouve. Et puis un commentaire, tu peux trouver des gens qui ne les lisent pas, les tests seront toujours exécutés.
Posté par _kaos_ .
Évalué à 3.
Dernière modification le 31 décembre 2021 à 08:08.
À priori j'écris plutôt un test.
Je dirais que c'est complémentaire. Le commentaire évite au développeur de se lancer inutilement dans du code qui sera manifestement problématique, le test apporte l'assurance que ce code ne devrait pas sortir après la phase de tests. Le test peut être utile pour le refactoring, le commentaire apporte peu ou rien pour cela à priori.
Et moi que c'est redondant. Représenter la même chose 2 fois est le meilleur moyen de créer des incohérences.
les tests seront toujours exécutés.
Ah, tiens. On m'aurait menti ? :p
Notre outillage lance les tests avant de construire le binaire final (sauf si tu lui demande). Notre intégration continue les lance elle aussi et vérifie la couverture des branches. Déjouer toutes les vérification s'apparente plus à du sabotage.
Du coup, tu as du code qui va être modifié par quelqu'un qui ne se rendra pas compte que ça modification introduit un bug avant que le test échoue alors qu'un commentaire aurait indiquer la chose tout de suite ?
« Rappelez-vous toujours que si la Gestapo avait les moyens de vous faire parler, les politiciens ont, eux, les moyens de vous faire taire. » Coluche
Posté par barmic 🦦 .
Évalué à 2.
Dernière modification le 31 décembre 2021 à 11:03.
Si le commentaire était à jour, s'il avait été lu, s'il avait été mis au bon niveau, s'il avait été compris,… Oui.
Mais c'est une question de documentation par les tests, c'est aussi une question de méthodologie, si tu applique le TDD tu n'aura pas touché au code de production.
L'un n'interdit pas complètement l'autre, mais l'un est obligatoire l'autre est optionnel et induit un coup qui me paraît bien plus important que son gain (on ne passe pas des heures sans lire les tests ou les lancer).
Généralement on le met quand le bug appel à un code vraiment WTF.
Mais c'est une question de documentation par les tests, c'est aussi une question de méthodologie, si tu applique le TDD tu n'aura pas touché au code de production.
La question revient au même le jour où tu dois modifier le test.
Généralement on le met quand le bug appel à un code vraiment WTF.
Tout le monde n'a pas la même notion de WTF mais oui, il me semble que vu les points précédents, il n'est pas question de commenter le code si le comportement est attendu.
« Rappelez-vous toujours que si la Gestapo avait les moyens de vous faire parler, les politiciens ont, eux, les moyens de vous faire taire. » Coluche
La question revient au même le jour où tu dois modifier le test.
Je ne comprends pas. Ce que je veux dire c'est que tu me dis que le gars va modifier le code puis se rendre compte dans les tests que ça invalide un test. Je suis que c'est une question de méthode s'il commence par les tests (en fait même pas une question de TDD juste du test first) ce ne sera pas le cas.
Tout le monde n'a pas la même notion de WTF mais oui, il me semble que vu les points précédents, il n'est pas question de commenter le code si le comportement est attendu
Alors qu'un défaut c'est bien plus objectif donc. Écrire un test pour chaque défaut (le développeur précédent est passé à côté du cas donc ça mérite un cas de test) et un commentaire dans certains cas (et ça peut se décider au second qui passe dessus et qui trouve que finalement ça mérite un commentaire).
Mais ce dernier point n'est pas nécessairement lié à un bug. La règle serait plus : un code wtf (parce qu'on doit se caler sur un comportement bizarre ou parce qu'on arrive pas à rendre le code plus clair) mérite un commentaire.
J'aurai tendance à dire que les deux se complètent et ne répondent pas au même besoin. Les commentaire du code servent pendant qu'on parcoure le code source et doivent réflecter l'état du moment (pas seulement programmatiquement) Les messages de commit doivent donner les indications sur l'évolution du code (et le journaliser) sans forcément être tout aussi technique (toute façon presque personne ne lit le message détaillé…) Cf. https://reflectoring.io/meaningful-commit-messages/ pour les messages de commit.
“It is seldom that liberty of any kind is lost all at once.” ― David Hume
# Rule 8: Add comments when fixing bugs
Posté par HL . Évalué à 3.
J'ai un petit peu du mal avec cette règle, elle ne devrait être appliquée que si le commentaire apporte une information utile.
Pour le premier exemple c'est très bien parce qu'il est question du comportement d'un composant tiers. Le second exemple, j'y crois un peu moins.
[^] # Re: Rule 8: Add comments when fixing bugs
Posté par Psychofox (Mastodon) . Évalué à 5.
Euh et quel serait l'intérêt de mettre un commentaire qui n'apporte pas d'info utile?
[^] # Re: Rule 8: Add comments when fixing bugs
Posté par HL . Évalué à 1.
Comprendre par là : « ne pas appliquer cette règle systématiquement, à chaque correction de bug ».
[^] # Re: Rule 8: Add comments when fixing bugs
Posté par Gil Cot ✔ (site web personnel, Mastodon) . Évalué à 4.
À lier aux autres règles : bien sûr que tu ne mets pas de commentaire si ça n'apporte rien ; mais souvent la correction d'un bogue va réécrire un bout de code d'une façon moins triviale qu'il faut expliquer en commentaire pour éviter que quelqu'un réintroduise le bogue subtil en simplifiant le code plus tard.
“It is seldom that liberty of any kind is lost all at once.” ― David Hume
[^] # Re: Rule 8: Add comments when fixing bugs
Posté par _kaos_ . Évalué à 4.
Sans considération sur la trivialité ou non d'une réécriture, la simple notification de la correction d'un bug invite à consulter l'historique (qui en général va contenir des détails sur le bug dont l'ancienne implémentation). C'est bien éviter sa réintroduction qu'on cherche à éviter, donc autant avoir ce qui ne marche pas "sous le coude".
Même sans explication, l'information est mise à disposition pour celui qui souhaite creuser les détails (tout comme une référence lors d'un copier/coller).
Matricule 23415
[^] # Re: Rule 8: Add comments when fixing bugs
Posté par Elfir3 . Évalué à 4.
J'ajouterais que dans certaines boites, la consultation de l'historique est une pratique digne d'un rituel satanique réservé au praticien des arcanes dont l'âme a été morcelée afin de pouvoir la revendre a plusieurs entités.
Petite anecdote relativement liée, je suis d'ailleurs un jour tombé dans une équipe d'ingénieurs qui m'ont mis en garde contre l'utilisation du bouton "Blame" de jira, ne voulant pas attirer d'ennui au développeur ayant fait le commit… Des gens très compétents pourtant. Je garderai toujours un doute sur le fait qu'ils étaient sérieux.
[^] # Re: Rule 8: Add comments when fixing bugs
Posté par barmic 🦦 . Évalué à 6.
À priori j'écris plutôt un test. C'est plus vivant et ça documente mieux je trouve. Et puis un commentaire, tu peux trouver des gens qui ne les lisent pas, les tests seront toujours exécutés.
https://linuxfr.org/users/barmic/journaux/y-en-a-marre-de-ce-gros-troll
[^] # Re: Rule 8: Add comments when fixing bugs
Posté par _kaos_ . Évalué à 3. Dernière modification le 31 décembre 2021 à 08:08.
Je dirais que c'est complémentaire. Le commentaire évite au développeur de se lancer inutilement dans du code qui sera manifestement problématique, le test apporte l'assurance que ce code ne devrait pas sortir après la phase de tests. Le test peut être utile pour le refactoring, le commentaire apporte peu ou rien pour cela à priori.
Ah, tiens. On m'aurait menti ? :p
Matricule 23415
[^] # Re: Rule 8: Add comments when fixing bugs
Posté par barmic 🦦 . Évalué à 3.
Et moi que c'est redondant. Représenter la même chose 2 fois est le meilleur moyen de créer des incohérences.
Notre outillage lance les tests avant de construire le binaire final (sauf si tu lui demande). Notre intégration continue les lance elle aussi et vérifie la couverture des branches. Déjouer toutes les vérification s'apparente plus à du sabotage.
https://linuxfr.org/users/barmic/journaux/y-en-a-marre-de-ce-gros-troll
[^] # Re: Rule 8: Add comments when fixing bugs
Posté par claudex . Évalué à 6.
Du coup, tu as du code qui va être modifié par quelqu'un qui ne se rendra pas compte que ça modification introduit un bug avant que le test échoue alors qu'un commentaire aurait indiquer la chose tout de suite ?
« Rappelez-vous toujours que si la Gestapo avait les moyens de vous faire parler, les politiciens ont, eux, les moyens de vous faire taire. » Coluche
[^] # Re: Rule 8: Add comments when fixing bugs
Posté par barmic 🦦 . Évalué à 2. Dernière modification le 31 décembre 2021 à 11:03.
Si le commentaire était à jour, s'il avait été lu, s'il avait été mis au bon niveau, s'il avait été compris,… Oui.
Mais c'est une question de documentation par les tests, c'est aussi une question de méthodologie, si tu applique le TDD tu n'aura pas touché au code de production.
L'un n'interdit pas complètement l'autre, mais l'un est obligatoire l'autre est optionnel et induit un coup qui me paraît bien plus important que son gain (on ne passe pas des heures sans lire les tests ou les lancer).
Généralement on le met quand le bug appel à un code vraiment WTF.
https://linuxfr.org/users/barmic/journaux/y-en-a-marre-de-ce-gros-troll
[^] # Re: Rule 8: Add comments when fixing bugs
Posté par claudex . Évalué à 4.
La question revient au même le jour où tu dois modifier le test.
Tout le monde n'a pas la même notion de WTF mais oui, il me semble que vu les points précédents, il n'est pas question de commenter le code si le comportement est attendu.
« Rappelez-vous toujours que si la Gestapo avait les moyens de vous faire parler, les politiciens ont, eux, les moyens de vous faire taire. » Coluche
[^] # Re: Rule 8: Add comments when fixing bugs
Posté par barmic 🦦 . Évalué à 2.
Je ne comprends pas. Ce que je veux dire c'est que tu me dis que le gars va modifier le code puis se rendre compte dans les tests que ça invalide un test. Je suis que c'est une question de méthode s'il commence par les tests (en fait même pas une question de TDD juste du test first) ce ne sera pas le cas.
Alors qu'un défaut c'est bien plus objectif donc. Écrire un test pour chaque défaut (le développeur précédent est passé à côté du cas donc ça mérite un cas de test) et un commentaire dans certains cas (et ça peut se décider au second qui passe dessus et qui trouve que finalement ça mérite un commentaire).
Mais ce dernier point n'est pas nécessairement lié à un bug. La règle serait plus : un code wtf (parce qu'on doit se caler sur un comportement bizarre ou parce qu'on arrive pas à rendre le code plus clair) mérite un commentaire.
https://linuxfr.org/users/barmic/journaux/y-en-a-marre-de-ce-gros-troll
# Commentaire supprimé
Posté par Anonyme . Évalué à 4.
Ce commentaire a été supprimé par l’équipe de modération.
[^] # Re: re: Best practices for writing code comments
Posté par Gil Cot ✔ (site web personnel, Mastodon) . Évalué à 3.
J'aurai tendance à dire que les deux se complètent et ne répondent pas au même besoin. Les commentaire du code servent pendant qu'on parcoure le code source et doivent réflecter l'état du moment (pas seulement programmatiquement) Les messages de commit doivent donner les indications sur l'évolution du code (et le journaliser) sans forcément être tout aussi technique (toute façon presque personne ne lit le message détaillé…) Cf. https://reflectoring.io/meaningful-commit-messages/ pour les messages de commit.
“It is seldom that liberty of any kind is lost all at once.” ― David Hume
# à lire aussi
Posté par BFG . Évalué à 4.
http://antirez.com/news/124
[^] # Re: à lire aussi
Posté par Gil Cot ✔ (site web personnel, Mastodon) . Évalué à 5.
Un très bon complément qui annonce bien la couleur
“It is seldom that liberty of any kind is lost all at once.” ― David Hume
Suivre le flux des commentaires
Note : les commentaires appartiennent à celles et ceux qui les ont postés. Nous n’en sommes pas responsables.