Récemment, j'ai travaillé sur la refactorisation de parties de la base de code que je traite actuellement - non seulement pour mieux le comprendre moi-même, mais aussi pour le rendre plus facile pour les autres qui travaillent sur le code.
J'ai tendance à me pencher du côté de penser que le code auto-documenté est agréable . Je pense juste que c'est plus propre et si le code parle de lui-même, eh bien ... C'est super .
D'autre part, nous avons une documentation telle que javadocs. J'aime aussi cela, mais il y a un certain risque que les commentaires ici deviennent obsolètes (ainsi que les commentaires en général bien sûr). Cependant, s'ils sont à jour, ils peuvent être extrêmement utiles, par exemple pour comprendre un algorithme complexe.
Quelles sont les meilleures pratiques pour cela? Où tracez-vous la frontière entre le code auto-documenté et les javadocs?