Des commentaires dans le code

Les commentaires sont en programmation informatique, des portions du code source ignorées par le compilateur ou l’interpréteur, car destinées en général à un lecteur humain et non censées influencer l’exécution du programme.

Rôles essentiels

Donner des indications de lecture du code

Sur la structure interne (comment ça marche ?)
Sur la structure externe (comment ça s’utilise ?)

Inactiver des lignes de code

Faciliter la mise au point
Mémoriser une instruction devenue inutile mais dont le besoin pourrait réapparaitre

Des commentaires de lecture

Commentaires de code « interne »

Concernent tout ce qui est invisible de l’extérieur
A destination du mainteneur (ici un programmeur !)

⇒ Attributs et code
Servent à expliquer le rôle d’une donnée et la logique de traitement employée

Commentaires de documentation « externe »

Concernent tout ce qui est visible de l’extérieur
A destination de l’utilisateur (aussi un programmeur !)

⇒ Classes, Méthodes et Événements publics
Servent à fabriquer la documentation technique Voir javadoc tags

Qualité des commentaires

Les commentaires sont faits pour être compris par vous ET d’autres que vous !!!

Les commentaires ne doivent pas faire référence à des classes utilisatrices, puisque par principe, on ne sait pas qui utilisera …

Ne pas confondre le descriptif du service rendu (« externe ») avec la façon de rendre le service (« interne »)