Salut,
Envoyé par
BluMonky
à quoi doit ressembler exactement la syntaxe d'un nom d'élément et que doivent décrire exactement les commentaires ?
Salut,
Pour ce qui est des identifiants
(je préfère parler d'identifiants plutôt que de "noms" pour éviter toute confusion 
) il faut faire en sorte qu'ils décrivent par eux mêmes la "raison d'être" de ce qu'ils identifient, par exemple:
- pour un type de donnée, tu peux choisir le mot qui désigne le "concept" que tu veux représenter : Voiture, Avion, Pistolet, Personnage représentent des concepts que tout le monde connait
- pour une donnée (qu'il s'agisse d'une constante ou d'une variable), choisi un idientifiant qui explique clairement l'usage qui en sera fait comme voitureDeJhon,escadrilleDavionDeChasse, pistoletAViseeLaser, ...
- pour les fonctions essaye d'en décrire l'objectif. Ce sera sans doute sous forme d'un verbe (et de ses compléments), par exemple : trier ou trierParOrdreCroissant ...
- Si la fonction agit d'avantage comme une question dont tu attends la réponse, essaye de poser la question: estEnVie, estActif, aDesMunitions ...
Cela va permettre à ton code de "raconter une histoire" à la personne qui le lit, ce qui permettra à la personne qui le lit de ... comprendre ton code plus facilement
Pour ce qui est des commentaires
De manière générale, il faut partir du principe que le meilleur commentaire, ce sera toujours celui que l'on n'aura pas besoin d'écrire.
Si, en relisant ton code, tu te dis "Houlala... je n'arrive déjà plus à comprendre ce que je voulais faire, je vais ajouter un commentaire", c'est que tu as déjà loupé quelque chose...
Il y a de fortes chances que, si tu change le nom d'une variable ou d'une fonction, tu puisse arriver à faire en sorte que ton code s'explique par lui meme, en commencant à te "raconter l'histoire" de ce qu'il fait.
Autrement, tu as trois grosses catégories de commentaires:
a- les "cartouches"
Il s'agit le plus souvent de commentaires placés avant la définition d'un type de donnée (classe, structure ou énumération) ou avant le prototype d'une fonction qui tente d'expliquer la raison d'être de l'élément commenté.
Si tu utilises un format approprié (par exemple le format reconnu par doxygen) ils te permettront de générer automatiquement la documentation de ton projet Par exemple:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
| /** @brief représente le niveau d'agressivité envers le joueur
*
* La réaction des rencontres faites par le joueur à son encontre dépendra
* de leur niveau d'agressivité :
*
* Affole : la rencontre s'enfuit de manière désordonnée à l'approche du joueur
* Apeure : la rencontre essaye de se cacher à l'approche du joueur
* Craintif : la rencontre observe le joueur avec suspiscion
* Neutre : la rencontre semble ne pas faire attention au joueur
* Rancunier : la rencontre n'attend d'une raison valable pour attaquer le joueur
* Agressif : la rencontre attaque le joueur "à vue"
*/
enum class Agressivite{
Affole,
Apeure,
Craintif,
Neutre,
Rancunier
Agressif,
}; |
(Evidemment, on peut faire la même chose pour les fonctions, je n'ai simplement pas d'exemple en tête pour l'instant )
Ce genre de commentaire explique tout ce qu'il faut savoir pour utiliser "correctement" l'énumération "Agressivite", sans donner plus de détail que nécessaire.
Si tu abandonne ton projet pour deux mois, un an ou même dix ans, lorsque tu reviendra dessus et que tu reliras ton commentaire, tu sauras exactement pourquoi tu as créé cette énumération, et l'objectif du commentaire sera atteint
Les commentaires à visée didactiques :
Il y a un fait indéniable: c'est que le code que l'on va présenter à quelqu'un qui découvre à peine la programmation va plus être perçu par "l'élève" comme un sorte "d'incantation magique" que comme quelque chose de parfaitement structuré dont chaque instruction a sa propre raison d'être et, surtout, d'excellentes raisons de se trouver exactement à cet endroit particulier plutôt qu'ailleurs.
Si l'on veut que "l'élève" puisse avoir "la moindre chance" d'arriver à comprendre ce que fait le code donné en exemple, il va falloir trouver un moyen de lui expliquer et, de préférence, trouver un moyen pour que les explications soient "directement rattachées" à la partie du code qu'elles doivent expliquer.
Le meilleur moyen d'y parvenir étant ... d'introduire dans le code ce que l'on peut appeler des "commentaires (à visée) didactiques". Par exemple (tiré de ton propre code):
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
|
/* pour chaque actions se trouvant dans la liste
* des actions potentielles du joueur
*/
for (auto& action : joueur.liste_actions)
{
/* si l'action envisagée est de classe "combat"
* on rend l'action en question accessible, autrement
* (c'est à dire : si l'action est de classe "menu")
* on la rend inaccessible.
*/
if (action.classe == "combat")
{
action.avaible = true;
}
else if (action.classe == "menu")
{
action.avaible = false;
}
} |
(Note au passage que le fait d'avoir exprimé la logique mise en place pourrait t'inciter à l'améliorer d'une manière ou d'une autre, ce qui pourrait être bénéfique au final )
On remarquera que ce sont des commentaires qui paraphrasent énormément le code, ce qui est généralement une mauvaise chose (*). Cependant, leur présence est tolérée -- pour ne pas dire "rendue indispensable" -- par le fait que le seul but de ce code et des commentaires qui y sont associés est justement de permettre à la personne qui lit le code de comprendre "ce qui est fait et pourquoi".
Et pourtant, si la présence de tels commentaires et tolérée dans un code qui a pour but de permettre à "un élève" de comprendre le code présenté en exemple, ils ne devraient jamais se retrouver dans un code de "production"
(*) Généralement, les commentaires qui paraphrasent le code sont très mal vus parce qu'il y a une très forte probabilité pour qu'ils ne soient pas mis à jour si le code vient à être modifié.
On risque alors de se retrouver avec des commentaires qui "expliquent quelque chose" alors que le code "fait autre chose", ce qui embrouille l'esprit du lecteur bien plus que ce que les commentaires -- s'ils avaient été à jour -- n'auraient pu l'aider à comprendre.
Et c'est d'autant plus vrai que la plupart des gens préféreront lire les commentaires, qui ont l'avantage d'être écrits sous une forme "facilement compréhensible" plutôt que le code qui reste -- quoi qu'il arrive -- plutôt "cryptique".
Les commentaires totalement inutiles
La dernière catégorie est celle qui regroupe "tous ces commentaires" qui ... ne servent absolument à rien parce qu'ils n'apportent aucune "plus value" dans le code.
Par exemple :
a = a *2; // multiplie la valeur de a par deux
Sans blagues ??? ... j'étais persuadé que cette ligne avait pour objectif d'additionner les valeurs de b et de c et de donner le résultat à d ....
(et si tu ne crois pas celle-là, je t'en raconterai une autre )
Dans bien des cas, les commentaires pourraient être rendus inutiles simplement en améliorant le code, entre autre, au niveau du respect des principes SOLID dont (principalement, mais pas que) le fait de respecter le SRP (Single Responsability Principle ou principe de la responsabilité unique), qui correspond au S de SOLID.
Par exemple, sur la même page que l'exemple précédent, on trouve, dans une seule et unique fonction les commentaires:
// Boucles rendant les actions pour le combat disponibles et celles pour le menu principal indisponibles
(ligne 29)
// Sert à afficher les cinématiques
(ligne 82)
// Initialisation des variables pour le combat
(ligne 91)
// Remise des entités à leur état d'origine
(ligne 157) et, à la fin de la fonction
// Boucles rendant les actions pour le menu principal disponibles et celles pour le combat indisponibles
(ligne 181)
Je ne peux m'empêcher de penser ces commentaires démontrent que tu avais déjà au minimum "l'intuition" que "quelque chose cloche" dans ton code, que les différentes étapes décrites par les commentaires, que le code permettant à ces étapes d'exister n'avait "aucune raison" d'être regroupé au sein d'une seule et unique fonction.
Et, en vertu du SRP, ton intuition était parfaitement justifiée, car tu te retrouve avec une seule fonction (la fonction combat) qui se retrouve à faire ... cinq choses différentes. Qui se retrouve avec cinq responsabilités. Ce qui en fait quatre de trop.
Si tu avais fait en sorte que chacune de ses responsabilités soit prise par une fonciton spécifique, le code de la fonction combat aurait pu se limiter (par exemple) à quelque chose comme
1
2
3
4
5
6
7
8
| bool combat(entity& joueur, entity& ennemi, int& niveau){
std::chrono::milliseconds pause(500);
changeActionMode(joueur,"combat");
changeActionMode(ennemi,"combat");
jouerCinematiques(niveau);
battezVous(joueur, ennemi);
resetApresCombat(joueur, ennemi);
} |
et chacune des fonctions appelée aurait pu correspondre à une étape bien particulière, ce qui aurait eu l'énorme intérêt de ... permettre de les réutiliser "ailleurs" en cas de besoin
Mais, du coup, les commentaires pourraient parfaitement être supprimer sans nuire à la compréhension car ... le code nous "raconte" déjà la même histoire que celle que tu as décidé de nous raconter au travers des commentaires
Présentation de mon dernier projet en C++
Répondre avec citation
A méditer: La solution la plus simple est toujours la moins compliquée
(et il y a pire - ou mieux ? - l'utilisation de l'assembleur 
.
Partager