Je te rejoins complètement. Le code doit se lire comme un bouquin et un livre dans lequel il faut sans cesse se référer à des notes de bas de page c'est lourd à lire. Ceux qui ont tenté de lire une version traduite de l'Art de la Guerre de Sun Zu savent de quoi je parle : C'est bourré de notes historiques, d'explications de termes intraduisibles ou de concepts inconnus. Le code sera relu des centaines de fois pas des personnes différentes. Il doit donc être compréhensible de loin par quelqu'un qui a le même background. Si on fait du traitement du signal par exemple, on peut supposer que le lecteur sait ce qu'est une transformée de Fourier. Pas la peine de mettre un pavé de texte expliquant l'algo.
Je met en général peu d'explications dans le code. Lorsque je met des commentaires, c'est pour expliquer ce qui semble non naturel (workaround pour un problème connu, etc) ou que quelqu'un pourrait prendre pour un bug/oubli/boulette alors que c'est voulu. Ca ne dispense pas de faire de la doc en particulier sur l'architecture et les choix effectués mais la place de ce type d'info n'est pas dans le code. Quelqu'un qui cherche à comprendre l'architecture du logiciel ne devrait pas avoir à aller fouiller dans les fichiers pour avoir une vue d'ensemble et savoir dans quelle partie du code il doit intervenir.
[^] # Re: commenter le code?
Posté par Croconux . En réponse au journal à quand un code commenté ?. Évalué à 4.
Je met en général peu d'explications dans le code. Lorsque je met des commentaires, c'est pour expliquer ce qui semble non naturel (workaround pour un problème connu, etc) ou que quelqu'un pourrait prendre pour un bug/oubli/boulette alors que c'est voulu. Ca ne dispense pas de faire de la doc en particulier sur l'architecture et les choix effectués mais la place de ce type d'info n'est pas dans le code. Quelqu'un qui cherche à comprendre l'architecture du logiciel ne devrait pas avoir à aller fouiller dans les fichiers pour avoir une vue d'ensemble et savoir dans quelle partie du code il doit intervenir.