tout est une question de l'endroit ou tu mets le curseur entre trop de doc et pas de doc. Dans certaines méthodes à Gilles, la règle, c'est zéro commentaire dans le code. (option "Si le code a besoin d'être commenté pour être compris, c'est du mauvais code")
Il faut distinguer la doc interne et la doc d'API à destinations de développeurs tiers. Si getTitle fait partie d'une interface externe, il faut la documenter au moins succinctement (ne serait-ce que pas un lapidaire "self explaining"). Si c'est un bout de doc interne à un module, perso, je ne documenterais pas, parce ce que le développeur qui coincerait déjà à ce niveau là, ce serait pas la peine qu'il regarde plus loin.
En fonction du contexte dans lequel est englobé ce bout de code, les 4 lignes de commentaires seront plus ou moins utiles. J'aurais tendance à dire plutôt moins, mais c'est un exemple un peu caricatural. Les IDEs qui génèrent des getter/setter en profitent parfois pour écrire les 3 lignes de doc qui vont avec.
concernant ton titre, cf mon commentaire plus haut. La doc obsolète, en plus d'être inutile, peut-être nuisible si on ne sait pas qu'elle est obsolète.
[^] # Re: La doc est toujours utile
Posté par gaaaaaAab . En réponse au journal De tout, de rien, des liens, bla bla bla. Évalué à 4.
tout est une question de l'endroit ou tu mets le curseur entre trop de doc et pas de doc. Dans certaines méthodes à Gilles, la règle, c'est zéro commentaire dans le code. (option "Si le code a besoin d'être commenté pour être compris, c'est du mauvais code")
Il faut distinguer la doc interne et la doc d'API à destinations de développeurs tiers. Si getTitle fait partie d'une interface externe, il faut la documenter au moins succinctement (ne serait-ce que pas un lapidaire "self explaining"). Si c'est un bout de doc interne à un module, perso, je ne documenterais pas, parce ce que le développeur qui coincerait déjà à ce niveau là, ce serait pas la peine qu'il regarde plus loin.
En fonction du contexte dans lequel est englobé ce bout de code, les 4 lignes de commentaires seront plus ou moins utiles. J'aurais tendance à dire plutôt moins, mais c'est un exemple un peu caricatural. Les IDEs qui génèrent des getter/setter en profitent parfois pour écrire les 3 lignes de doc qui vont avec.
concernant ton titre, cf mon commentaire plus haut. La doc obsolète, en plus d'être inutile, peut-être nuisible si on ne sait pas qu'elle est obsolète.