Tu parles de documentation d'API et non de commentaire. En effet c'est une bonne pratique de savoir exactement ce que ta méthode va faire et comment elle va le faire avant de commencer à l'écrire (cf. "pseudocode programming process" dans l'excellent Code Complete).
Cependant les commentaires tu ne peux généralement les décider et les écrire correctement qu'une fois que le code existe. Je trouve que la nouvelle classe String de Java est un bon exemple:
Le grain des méthodes est bon, le code est simple et se lit naturellement
La documentation de l'API est excellente bonne
Les commentaires sont présent uniquement lorsqu'il y a besoin de souligner l'intention ou un fait particulier et ne sont absolument pas redondant avec le code.
C'est assez facile à faire pour des classes simples comme String. Par contre plus ta classe à de métier ou d'interaction avec l'extérieur plus tu vas avoir le logique à expliciter dans le code. Genre ca ou c'est très difficile de garder un code limpide à long terme et ou beaucoup de choses doivent être explicitées.
[^] # Re: Commenter l'intention
Posté par ckyl . En réponse au journal To comment or not to comment. That is the question.. Évalué à 3. Dernière modification le 23 avril 2013 à 11:43.
Tu parles de documentation d'API et non de commentaire. En effet c'est une bonne pratique de savoir exactement ce que ta méthode va faire et comment elle va le faire avant de commencer à l'écrire (cf. "pseudocode programming process" dans l'excellent Code Complete).
Cependant les commentaires tu ne peux généralement les décider et les écrire correctement qu'une fois que le code existe. Je trouve que la nouvelle classe String de Java est un bon exemple:
C'est assez facile à faire pour des classes simples comme String. Par contre plus ta classe à de métier ou d'interaction avec l'extérieur plus tu vas avoir le logique à expliciter dans le code. Genre ca ou c'est très difficile de garder un code limpide à long terme et ou beaucoup de choses doivent être explicitées.