Wiki SIO Chaptal

Outils pour utilisateurs

Outils du site

Piste : • composer
bloc2:prog:gen:commentaires-de-code

Différences

Ci-dessous, les différences entre deux révisions de la page.

Lien vers cette vue comparative

Les deux révisions précédentesRévision précédente
Prochaine révision		Révision précédente
bloc2:prog:gen:commentaires-de-code [2023/03/23 11:34] – supprimée - modification externe (Unknown date) 127.0.0.1bloc2:prog:gen:commentaires-de-code [2023/03/23 19:18] (Version actuelle) – [Qualité des commentaires] admin
Ligne 1: Ligne 1:
 +====== 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 =====
 +<WRAP center round tip 70%>
 +**<color blue>Donner des indications de lecture du code</color>**
 +----
 +  * <color green>Sur la structure interne (comment ça marche ?)</color>
 +  * <color green>Sur la structure externe (comment ça s’utilise ?)</color>
 +</WRAP>
 +<WRAP center round tip 70%>
 +**<color blue>Inactiver des lignes de code</color>**
 +----
 +  * <color green>Faciliter la mise au point</color>
 +  * <color green>Mémoriser une instruction devenue inutile mais dont le besoin pourrait réapparaitre</color>
 +</WRAP>
 +
 +
 +
 +
 +
 +
 +===== Des commentaires de lecture =====
 +<WRAP group>
 +<WRAP half column >
 +<WRAP center round box >
 +**<color blue>Commentaires de code « interne »</color>**
 +----
 +  * 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
 +</WRAP>
 +</WRAP>
 +
 +<WRAP half column>
 +<WRAP center round box >
 +**<color blue>Commentaires de documentation « externe »</color>**
 +----
 +  * 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 [[https://idratherbewriting.com/learnapidoc/nativelibraryapis_javadoc_tags.html|javadoc tags]]
 +</WRAP>
 +</WRAP>
 +</WRAP>
 +
 +
 +
 +===== Qualité des commentaires =====
 +<WRAP round important 67%>
 +**Les commentaires sont faits pour être compris par vous __<color #22b14c>ET d’autres que vous</color>__ !!!**
 +</WRAP>
 +<  a2s  >
 +.---.
 +| | |
 +| | |
 +| v |
 +.---.
 +</a2s>
 +<WRAP center round important 75%>
 +**Les commentaires ne doivent pas faire référence à des classes utilisatrices, puisque par principe, on ne sait pas qui utilisera …**
 +</WRAP>  
 +<  a2s  >
 +.---.
 +| | |
 +| | |
 +| v |
 +.---.
 +</a2s><WRAP right round important 73%>
 +**Ne pas confondre le descriptif du service rendu (« externe ») avec la façon de rendre le service (« interne »)**
 +</WRAP>