De l'utilité des commentaires dans les sources

Question

Bonsoir à toutes et tous ! Voici le but et l'origine de ce message: j'ai souvent constaté, sur les différents sites de CodeS-SourceS, des posts sur des codes réclamant plus de commentaires (je fais partie des auteurs de ces posts). Ça, c'est l'origine. Pour le but, je voulais simplement faire savoir à celles et ceux qui estiment que les commentaires représentent du temps perdu qu'ils se trompent. Un commentaire, même s'il semble anodin à son auteur peut avoir une grande importance. Je n'ai qu'un exemple à citer: je travaille au boulot sur Oracle, je développe en PL/SQL. Je suis tous les jours confronté à des packages contenant des procédures renvoyant ce qu'on appelle des "ref cursors". Pour faire simple, il s'agit de curseurs qui sont renvoyés en paramète OUT (dans le cadre du projet sur lequel je travaille, parce que des ref cursors peuvent être utilisés comme paramètres IN). La seule instruction que l'on rencontre généralement dans ce genre de procédure est "open for ", où est une requête SQL select. Le problème est que la quasi totalité de ces requêtes sont écrites sur plusieurs centaines de lignes, font appel à des fonctions, ont pas mal de jointures, de conditions dans les where clauses, ... et que quasiment aucune n'est commentée. Allez donc savoir à quoi elles servent, parce que les noms des procédures ne correpondent pas toujours à ce qu'elles font (je trouve cela étrange et anormal, mais qu'y puis-je, je suis arrivé sur le projet après 10 ans d'existance). Vous allez me dire "Pourquoi poster un message dans un forum C++ alors qu'il parle de PL/SQL ?". J'y viens... Remarquant que le manque de commentaires est parfois un frein au développement, je me suis mis à commenter mes sources. Et depuis peu, je me suis pas mal intéressé à doxygen, qui permet, à partir des commentaires des sources de plusieurs langages, de créer une doc. Très utile ! Comme je développe pas mal d'outils pour me simplifier la vie au boulot, en C++, que je passe à des collègues, je me suis dit que documenter avec doxygen avait un double intérêt: documenter pour moi (et ceux qui veulent continuer à documenter leurs changements après avoir adapté à leurs besoins), tout en proposant des commentaires pour ceux qui ne sont pas intéressés par la doc générée avec doxygen. Je peux assurer à tout le monde que c'est très utile, même quand le commentaire est succint. De plus, cela ne demande pas beaucoup plus de travail: si les commentaires contiennent des fautes d'orthographe, ça compile ! Je profite de ce message pour signaler à ceux qui, à l'instar d'un des mes ex-collègues, docteur en mathématiques et informatique (qui pensait tout connaître et qui ne savait pas que 1 n'est pas un nombre premier...), que les commentaires n'augmentent jamais la taille d'un exécutable (même si c'est un simple "Hello, world!" qui contient 5000 lignes de commentaires), ils sont ignorés par le compilo (si, si !!!). Il est maintenant clair que sur de petites sources (genre "gestion d'une liste d'élèves", gestion de mes CDs", et j'en passe et des meilleures), cela ne sert à rien... Mais certaines sources excellentes gagneraient à être plus commentées. Peut-être que si quelques-un(e)s commençaient à poster des sources avec des commentaires pour doxygen, en le stipulant, cela inciterait plus de monde à commenter. Je refais un saut sur le PL/SQL: je pense que je vais développer un des ce jours un système en PL/SQL qui serait utilisé comme doxygen, et quand ce sera prêt, je posterai dans la section "SQL". Mais ce n'est qu'un détail. J'espère recevoir des réactions concernant le ce post. Encore bonne soirée à toutes et à tous ! Exar.

BunoCS · Answer

Hello,
Je trouve également un code commenté est plus utile qu'un code brut que personne n'arrivera à relire après une longue pause...mais bon, chacun a sa vision des choses.
J'aime bien également Doxygen mais sur certains codes, je pense que c'est une "grosse artillerie"

@+
Buno
----------------------------------------
L'urgent est fait, l'impossible est en cours. Pour les miracles, prévoir un délai...

cptpingu · Answer

Je ne peux que plussoier tant de discernement !
Un code non commenté devrait être refusé (je parle au niveau d'une entreprise sérieuse, pas du réseau code source).
Doxygen est vraiment excellent, mais un commentaire classique, c'est déjà pas mal.

De l'utilité des commentaires dans les sources

2 réponses

Votre réponse

Discussions similaires