Faut-il ou non documenter le code source privé en Java ?

Cédric Beust s’interroge sur l’intérêt de documenter le code Java dont l’accès est privé. Car dans la majorité des cas, JavaDoc ignore ces commentaires. C. Beust documente ces champs ou ces méthodes qui ont un accès privé en autre parce qu’un IDE tel que Eclipse affiche une info-bulle avec le commentaire associé même si l’élément est privé.

Même si les personnes qui utilisent une API n’ont besoin de connaître que le fonctionnement public. Il faut avoir en tête que le code source de cette API sera sûrement modifié par différentes personnes. C’est à ce moment que la documentation des sections privées prend tout son sens.

Je ne me suis jamais posé de question sur l’utilité de la documentation du code privé[1]. Alors pensez aux personnes qui reliront votre code source.

Notes

[1] Et cette remarque ne va pas à l’encontre de la réflexion sur le code source et les commentaires.