Le problème, koala01, c'est que tu considères d'entrée de jeu que nous n'allons nous servir des commentaires que pour y écrire au mieux des évidences, au pire des âneries.
Là dans ton exemple, tu choisis une fonction dont nous n'avons aucune idée de ce qu'elle pourrait faire.
(je t'en fais une pire en Java si tu veux :
Object[] maFonction(Object[] args) throws Exception. Peut prendre n'importe quels arguments, renvoie une série de n'importe quoi (ou null, d'ailleurs...), et ne sait pas ce qui peut l'interrompre.
C'est la fonction universelle (
) : elle permet d'écrire un programme avec une seule fonction. On l'appelle avec des arguments différents et on met plein de if dedans...
Son problème ? Elle a effectivement existé, et je l'ai rencontrée...)
Je reprends ton premier exemple, en choisissant d'abord un thème à son sujet.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
| /** @brief Réalise une omelette ou un lardon grillé à partir d'ingrédients, s'ils sont frais.
* @param [in] oeuf Un oeuf. Peut valoir nullptr.
* @param [in] lardon Un lardon. Peut valoir nullptr.
* @return Une omelette aux lardons si possible, une omelette seulement ou un lardon grillé seulement, dans cet ordre, sinon.
* renvoie nullptr si aucun ingrédient n'a été fourni ou si aucun n'est consommable.
*/
Plat * create(Oeuf oeuf, Lardon lardon){
// Faire en priorité une omelette (aux lardons, si possible) si tous les ingrédients le permettent.
if(oeuf != nullptr && oeuf.isFrais())
{
return new Omelette(oeuf, lardon);
}
else
{
// Sinon, chercher à faire un lardon grillé.
if(lardon != nullptr && !lardon.isPerime())
{
return new LardonGrille(lardon);
}
}
return nullptr;
} |
(j'ai sûrement dû louper une instruction quelque-part, parce que le code ne s'illumine pas en C++)
La personne qui lit la documentation de cette fonction n'a pas besoin d'entrer dans son code pour l'analyser.
En passant son pointeur de souris au dessus d'elle, elle saura presque tout d'elle. Si le code de niveau d'appel supérieur est fait de dizaines d'appels d'autres fonctions, le temps gagné est important : on n'entre examiner le code des seules méthodes où l'on juge que cela va vraiment être utile.
Envoyé par grunt2000
Répondre avec citation
" "Dois-je supprimer ce commentaire indu et en écrire un qui soit en adéquation avec le code 
A méditer: La solution la plus simple est toujours la moins compliquée
.
Partager