méthode doit / commentaires de classe soient appliqués de manière cohérente ou sur une base de besoin seulement?

Question

Par souci de cohérence, je l'ai toujours appliqué les commentaires (sous la forme d'un JavaDoc) à toutes les méthodes et les classes, même si elles sont accesseurs simples et méthodes setters ou très petites classes d'emballage. Mais je cherche également à écrire du code autodocumenté ce qui rend souvent les commentaires superflus; à savoir les commentaires d'écriture uniquement en cas de besoin (et avant de le faire, essayez de réécrire le code de sorte que vous n'avez pas besoin du tout commentaire). Par conséquent, ces deux approches semblent contradictoires les uns aux autres.

Donc, si les commentaires qui décrivent une méthode ou une classe être appliquée d'une manière cohérente, ou si ces commentaires être écrit que lorsque la signification est pas tout à fait clairement de la définition?

Answer 1

Un simple test décisif serait de vérifier si la classe a plus de commentaires que le code. Si yest cela signifie que votre code est trop complexe et difficile à utiliser pour tout le monde.

Il est donc préférable d'écrire un code auto explicatif. De plus il n'y a pas besoin de commentaires d'écriture pour des choses qui sont évidentes comme setters et getters.

Je voudrais aller avec ces commentaires être écrit que lorsque la signification est pas tout à fait clairement de la définition.

Answer 2

J'ai utilisé pour créer un code pour chaque méthode, mais maintenant, je crée des documents que lorsque les remarques ajouter un peu plus d'informations que le code lui-même.

Voici une question sur un sujet similaire avec beaucoup de réponses. Avec l'évolution du code, il y a une chance que la mise à jour de la documentation est « oubliée ». Se référant à la question dans le lien mauvaise documentation est pire que pas de documentation du tout.