La notion de code source autodescriptif relèverait d’un mythe
Entretenu par les programmeurs qui n’ont pas saisi la portée de « documenter »
En programmation, l’écriture de code autodescriptif est une pratique qui implique le respect de certaines conventions de nommage et de programmation structurée. Eric Holscher affirme qu’il y a un amalgame au sein de la communauté des programmeurs en ce qui concerne cette pratique. Ce mélange a – de son point de vue – un impact négatif sur l’utilisabilité des logiciels et applications mis à disposition des personnes sans compétences en programmation.
Eric Holscher – cofondateur de ReadTheDocs, un service en ligne qui héberge de la documentation pour l’industrie du logiciel – entame son propos par une explication de la notion de commentaires. De son point de vue, ces derniers sont un sous-ensemble de la documentation qui devrait accompagner toute œuvre du génie logiciel.
Il va plus loin en ajoutant que ce sous-ensemble particulier est destiné à « documenter le pourquoi et non le comment », c’est-à-dire à : expliquer de précédentes approches qui n’ont pas fonctionné, faire apparaître de possibles améliorations, expliquer les compromis dans l’implémentation en cours, etc.
Ce sous-ensemble est à mettre en cohabitation avec les conventions de nommage et de programmation structurée au sein du code. Ces dernières viendraient ainsi jouer leur rôle qui est – selon lui – de « documenter le comment et non le pourquoi ».
Il semblerait cependant que certains programmeurs fassent fi de ce jeu de rôle et se limitent uniquement au respect des conventions de nommage et de programmation structurée pour affirmer que leur code source est « autodescriptif ». « Je n’ai plus besoin d’expliquer quoi que ce soit puisqu’il est désormais évident que le fonctionnement du programme est accessible à tous », leur attribue-t-il alors.
« Décider que les noms de variables [la convention de nommage] constituent la seule documentation requise signifie que seules les personnes qui lisent le code source peuvent en faire usage », déclare Eric Holscher pour s’indigner du fait que la documentation s’adresse en principe aux « utilisateurs de tous bords ».
Eric Holscher met ainsi de l’emphase sur le fait que la documentation du code va bien au-delà de la mise en œuvre du tandem de règles précédemment mentionné. Se limiter à respecter ces règles conduirait fatalement à exclure les personnes sans compétences en programmation de la liste des potentiels utilisateurs.
Il y a donc plus à faire que mettre côte à côte la « documentation du pourquoi et non du comment » et celle du « comment et non du pourquoi ». Il faudrait en plus penser à l’intégration d’éléments comme les tutoriels susceptibles de booster l’utilisabilité du logiciel ou de l’application déployée.
« Si vous tenez à avoir des utilisateurs pour les œuvres que vous produisez, il va falloir rédiger de la documentation », a-t-il conclu.
Source : blog
Et vous ?
Qu’en pensez-vous ?
Vous arrive-t-il de ne faire usage que des conventions de nommage au détriment des commentaires ?
Partagez-vous l’avis de l’auteur sur la portée qu’il attribue à la notion de documentation en génie logiciel ?
Voir aussi :
Programmation : quand faut-il commenter son code ? Google s'invite dans le débat et montre que les commentaires peuvent très souvent être évités
Débat qualité développement : Faut-il commenter son code source pour le rendre plus lisible et plus facile à maintenir ? Si oui comment ?
Partager