Ce qui est complètement crétin, évidemment, c'est de ne pas documenter son code. Ce n'est pas du temps perdu mais un investissement parce que, quand on se retrouve dessus après un certain temps, on perd moins de temps à comprendre ce qu'on a fait.
Je peux comprendre l'attrait de commenter son code, le problème, c'est qu'on a très peu d'outils pour aider à trouver des commentaires faux.
Si on oublie de free une variable, on a plein d'outils pour aider à trouver qu'on a oublié de free cette variable, si on fait un if (variable) à la place d'un if (not variable), on a des tests et un programme qui bugue, ce qui peut nous aider à trouver qu'on a oublié la négation.
La plupart des gros projets ont tous un tas d'outils pour trouver des bugs, et de la revue de code, et pourtant ont toujours plein de bugs.
Les commentaires, eux, n'ont pratiquement rien (juste la revue de code). Ce qui fait que les commentaires, qui eux sont très peu analysés, sont généralement la partie du code qui contient le plus de bug par ligne de commentaire. (par bug, j'entends commentaire qui ne dit pas ce que devrait faire le code)
Et si un commentaire est erroné, aucun outils ou tests ne va te dire qu'il est faux.
Et quand t'a déjà passé une demi-journée à te faire toute la Documentation d'une bibliothèque, car un commentaire te dit d'absolument appelle une autre fonction avant d'appeler celle dont tu as besoins, pour au final en lisant le code de la bibliothèque te rendre compte que le commentaire aurait juste dû être supprimé, car il concernait une ancienne version de la bibliothèque.
Bah, tu regardes les commentaires d'un autre œil.
Je ne dis pas qu'il ne faut pas commenter son code, mais c'est très facile d'oublier une négation dans une phrase, ou de changer la logique d'un code, et laisser les anciens commentaires qui explique l'ancienne logique.
C'est pour ça que les commentaires ne devrait être utilisé que pour dire ce que ne dit pas le code, ou faire de la Documentation utilisateur.
Et si un code à besoins d'être commenté, peut-être que c'est le code qui est trop compliqué et devrait être changé pour peu être avoir un code plus simple, voir qu'y s'auto-documente.
[^] # Re: Complètement crétin !
Posté par uso (site web personnel) . En réponse au journal Comment briller auprès de la gent féminine dans « le monde de la tech ». Évalué à 4.
Je peux comprendre l'attrait de commenter son code, le problème, c'est qu'on a très peu d'outils pour aider à trouver des commentaires faux.
Si on oublie de free une variable, on a plein d'outils pour aider à trouver qu'on a oublié de free cette variable, si on fait un if (variable) à la place d'un if (not variable), on a des tests et un programme qui bugue, ce qui peut nous aider à trouver qu'on a oublié la négation.
La plupart des gros projets ont tous un tas d'outils pour trouver des bugs, et de la revue de code, et pourtant ont toujours plein de bugs.
Les commentaires, eux, n'ont pratiquement rien (juste la revue de code). Ce qui fait que les commentaires, qui eux sont très peu analysés, sont généralement la partie du code qui contient le plus de bug par ligne de commentaire. (par bug, j'entends commentaire qui ne dit pas ce que devrait faire le code)
Et si un commentaire est erroné, aucun outils ou tests ne va te dire qu'il est faux.
Et quand t'a déjà passé une demi-journée à te faire toute la Documentation d'une bibliothèque, car un commentaire te dit d'absolument appelle une autre fonction avant d'appeler celle dont tu as besoins, pour au final en lisant le code de la bibliothèque te rendre compte que le commentaire aurait juste dû être supprimé, car il concernait une ancienne version de la bibliothèque.
Bah, tu regardes les commentaires d'un autre œil.
Je ne dis pas qu'il ne faut pas commenter son code, mais c'est très facile d'oublier une négation dans une phrase, ou de changer la logique d'un code, et laisser les anciens commentaires qui explique l'ancienne logique.
C'est pour ça que les commentaires ne devrait être utilisé que pour dire ce que ne dit pas le code, ou faire de la Documentation utilisateur.
Et si un code à besoins d'être commenté, peut-être que c'est le code qui est trop compliqué et devrait être changé pour peu être avoir un code plus simple, voir qu'y s'auto-documente.