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 »

Le , par Patrick Ruiz, Chroniqueur Actualités
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 ?


Vous avez aimé cette actualité ? Alors partagez-la avec vos amis en cliquant sur les boutons ci-dessous :


 Poster une réponse

Avatar de TiranusKBX TiranusKBX - Expert confirmé https://www.developpez.com
le 22/07/2017 à 20:50
Ce mec ne confond t'il pas la Documentation utilisateur et la documentation Technique ?
Le nom des variable si il doit être commenté c'est en doc technique pour une utilisation en tant que Lib ou pour les futurs mainteneurs du programme, pas pour une utilisation tout public.
Pour les programme de ma boite on tire au sort(3 programmeurs, le choix est rapide) qui vas faire la doc de nos programmes(pas pour les programmes de commande, le cahier des charges fait office de DOC et à chaque modifications le client doit le mettre à jour)
Avatar de raphchar raphchar - Membre confirmé https://www.developpez.com
le 23/07/2017 à 0:54
Citation Envoyé par Patrick Ruiz Voir le message
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.
Pour les logiciels et applications, l'utilisateur n'a rien a faire du code source et de ses commentaires. Pour une lib, le problème commence a survenir, mais il y a deux choses à distinguer : l'interface utilisateur, i.e. ce à quoi la lib donne accès et l'implem. Là, l'utilisateur n'a rien à faire de l'implem, qui est potentiellement privée. La documentation de type doxygen est peut -être utile, mais je préfère un petit tuto/exemple de base et des noms de fonctions explicites qui me permettent de ne pas consulter la doc, sauf dans des cas très particuliers. Documenter l'opération addition sur des entiers, ça n'a pas d'intérêt, documenter les opérations matricielles pour une lib de math, ça n'a pas d'intérêt, par contre documenter la différence entre deux manières différentes de construire une matrice peut être intéressant quand l'une est beaucoup plus rapide que l'autre.
Avatar de der§en der§en - Membre habitué https://www.developpez.com
le 23/07/2017 à 12:04
cofondateur de ReadTheDocs, un service en ligne qui héberge de la documentation pour l’industrie du logiciel : il me semble que tout est dit sur la raison de ces propos.

Je lui conseillerait de lire l'excellent Coder proprement.
Avatar de koyosama koyosama - Membre confirmé https://www.developpez.com
le 23/07/2017 à 17:08
J'etais jeune et je croyais aussi que le code commente ou la documentation ne servait a rien.

Je vais entendre dans ce post, les trucs classqiues :
  • Pas le temps de commente le code ou faire de la documentation
  • Pas besoin de commenter, le code est lisible
  • Il faut poser plus de questions


Enfin bon je vais evaluer ces trois points que j'entends souvent. Je pense qu'il y en a plus mais c'est les plus frequent.
Quand j'ai rejoint une companie super structure, j'ai decouvert ce qu'on peut etre le dilema pyramidale qu'on pouvait retrouvez chez big-blue ou dans les entreprises japonnaises.

Pas le temps de commente le code ou faire de la documentation
Je voudrais quand j'etais nouveau dans l'entreprise, j'ai aussi eu le cas, "Regarde la documentation (plutot : demerdes toi ...), je suis occupe pour le moment". Ironique non ...
Heuresement, pour moi ils avaient fait de la documentation . Et cette grace a cette doc que j'ai pu avance a mon travail, en posant les question sur le detail qui ets manquant et crucial sur un projet.
Dans le travail, je considere deux methodes car chaque personne a differente personnalite, culture, formation et curiosite.
Vous avez ceux qui cherchent et ceux qui cherchent pas, ceux qui osent poser des questions et ceux qui le font pas. Combien de fois j'ai entendu, oh regarde le jeune il pose beaucoup de questions ... Par contre dans le monde anglosaxons, Oh putains ils posent pas de question du tout.

La documentation est neccessaire peu importe le gens avec qui vous travailles, pour laisser des traces (procedure judiciaire, support techniques car vous travaillez pas tout seul, aide pour le stagiaire pour son rapport, echange ou vente de competence), pour comprendre un mecanisme. A chaque fois, j'entends toujours les memes dire, que le cas particuliers ne viendra jamais.

Par exemple, prenez un gars qui comme moi n'a pas d'experiences mais qui apprend super vite en observant et lisant les documentations pour rendre le produit sien. Certaines boites qui ont tendances a ne pas faire de docs auront tendances a vouloir recruter des seniors, des gens de prepas ou des gens avec 5 ans d'experiences, en gros le mouton a 5 pattes. Pourquoi, tout simplement parce qu'ils veulent pas formes. Dans cas la, je peux comprendre, mais on ferme des portes a gens qui peuvent etonner si on prend les mesures neccessaire pour le partage de connaissance. J'ai vu a sa Londres, et soi-disant ils ont "des penuries" (what a joke).

La documentation a des vertus plus pointus qu'on ne le pense quand on maitrise l'art du business et du management. Et personnellement, je pense qu'un developpeur qui fait que DE coder ne peut pas comprendre ces aspects car il a tres peu de chance de l'avoir appris.

Pas besoin de commenter, le code est lisible
Comme certain l'a expliquer, le but de dire Why ? C'est simplement d'expliquer le mecanisme. Prenons le cas d'une fontion :
Code : Sélectionner tout
afficher();
Ok le but c'est de comprendre ce qu'il fait, ce qu'il returne.
Pour l'instant, on peut le dire comme sa :
Code : Sélectionner tout
void afficher(stream output, stream content);
Bon c'est un peu mieux, on peut comprendre comment ce a besoin, ce qu'il ressort. Ok c'est cool sur un logiciel, un site-web, une application mobile, le classic quoi ...

Je n'ai pas plus le livre "Clean Code" ou encore "Refactorisation" (trop cher et trop gros :p). J'ai lu par contre celui la : "Practical Object Oriented Design in Ruby". Dans dix ans ou moi je suis parti a la retraite deja, je vais mettre mon application en VR (virtual reality). Sauf que le mechanisme interne que j'ai cree n'est pas du tout pour ce cas. Comment mon remplacent va devoir regler le probleme. Le meme probleme qui se pose quand un de vos services (operateur telephonique, service apres-vente, ...) fait pas bien son boulot, vous devriez pas faire pareil. Dite-vous que cela peut etre vous qui aller continuer ce projet, alors fiates les proprement.

Il faut poser plus de questions
Je ne sais pas quoi dire, a part que "officiellement", toutes questions ne sont pas idiotes. En realite ..., toutes les questions font **** tout le monde. Culture d'entreprise, culture francaise, culture de gars en costard, culture du "camra cafe". Je m'avancerais pas a point. Je ne suis pas magicien.

En somme :
La documentation est super importante, vous cherchez juste des excuse pour ne pas la faire. Mais toutes les vertus sont la. Le context pour le faire differt mais c'est une question de management. Et je pense que faire le radin ne resoudra rien sur le long terme.
Avatar de martopioche martopioche - Membre confirmé https://www.developpez.com
le 23/07/2017 à 18:57
Citation Envoyé par Patrick Ruiz Voir le message
Se limiter à respecter ces règles conduirait fatalement à exclure les personnes sans compétences en programmation de la liste des potentiels utilisateurs.
Heu, il y a une limite quand même…*Ce n'est pas le job du développeur et du code d'enseigner la programmation… Il est quand même attendu de celui qui met la main dans le code ou qui utilise ce code qu'il ai une compétence en programmation. D'ailleurs, Eric Holscher ne parle pas de personnes sans compétence en programmation mais des développeurs qui ne sont pas les développeurs du code en question…

Partagez-vous l’avis de l’auteur sur la portée qu’il attribue à la notion de documentation en génie logiciel
La documentation au sens large reste indispensable, que ce soit la documentation des fonctions/classes/modules que les commentaires. Anecdote personnelle : un "architecte" qui me pond une méthode et me dit "tu verra dans la signature comment elle s'utilise"… Ben non patate, ta collection en second paramètre, on sait que de temps en temps elle n'a rien, on peut lui passer un Null ? Idem en retour, quand il n'y a rien, c'est une collection vide ou Null (oui je parle de ce langage NullPointerExceptionGenerator )…

Le problème de cette mouvance résulte surtout des pseudo-agilistes qui ont omis dans "Des logiciels opérationnels plus qu’une documentation exhaustive" le mot "exhaustif" et qui retiennent "pas de documentation"…

Citation Envoyé par TiranusKBX Voir le message
Ce mec ne confond t'il pas la Documentation utilisateur et la documentation Technique ?
Quand on regarde la source, non, c'est le relais sur Developpez qui est mal rapporté.
Avatar de martopioche martopioche - Membre confirmé https://www.developpez.com
le 23/07/2017 à 18:59
Citation Envoyé par der§en Voir le message
cofondateur de ReadTheDocs, un service en ligne qui héberge de la documentation pour l’industrie du logiciel : il me semble que tout est dit sur la raison de ces propos.

Je lui conseillerait de lire l'excellent Coder proprement.
Tu ne connait pas ReadTheDocs toi…
Avatar de foetus foetus - Expert confirmé https://www.developpez.com
le 23/07/2017 à 19:01
Citation Envoyé par martopioche Voir le message
Le problème de cette mouvance résulte surtout des pseudo-agilistes qui ont omis dans "Des logiciels opérationnels plus qu’une documentation exhaustive" le mot "exhaustif" et qui retiennent "pas de documentation"…
Il me semble que les tests unitaires peuvent faire office de documentation
Avatar de super_navide super_navide - Provisoirement toléré https://www.developpez.com
le 23/07/2017 à 19:23
La bonne question est de ce poser c'est quoi un code source , un programme informatique, c'est quoi la différence entre le langage naturel et le langage de programmation.
Quand on a passer comme moi plus de 25 ans à coder, j'ai trouvé le code source est juste la représentation formel sans ambiguïté et déterministe du langage naturel.
Donc la question est simple pourquoi donc documenter/commenter un programme et ben il y a aucune raison pour le faire.
Mais en réfléchissant plus la seul et unique raison après pour commenter/documenter un programme est de prendre conscience que le développeur qui reprendra le code sera peut-être un boulet avec peut de capacité de compréhension limité.
Donc pour tous les développeurs amateurs ,incompétent et limité il faut forcement documenter/commenter son code.
Avatar de Pyramidev Pyramidev - Membre chevronné https://www.developpez.com
le 23/07/2017 à 21:41
Citation Envoyé par martopioche Voir le message
Anecdote personnelle : un "architecte" qui me pond une méthode et me dit "tu verra dans la signature comment elle s'utilise"… Ben non patate, ta collection en second paramètre, on sait que de temps en temps elle n'a rien, on peut lui passer un Null ? Idem en retour, quand il n'y a rien, c'est une collection vide ou Null (oui je parle de ce langage NullPointerExceptionGenerator )…
Dans un langage comme le Java ou le C qui contient le type "référence qui peut être nulle" sans contenir le type "référence forcément non nulle", en pratique, la plupart des fonctions qui retournent des références retournent des références jamais nulles et la plupart des appels des fonctions sont pensés comme si les arguments n'étaient jamais nuls.
Du coup, à mon avis, avec un tel langage, le mieux est d'adopter une convention qui stipule que toutes les références sont non nulles par défaut. Si une fonction peut retourner une référence qui peut être nulle, il faut alors le signaler explicitement, par exemple avec un suffixe "_canBeNull". C'est moins dangereux que d'espérer que l'utilisateur de la fonction va vérifier dans la documentation si la fonction fait partie des rares fonctions à retourner une référence qui peut être nulle. On peut aussi utiliser le suffixe "_canBeNull" dans des noms de paramètre.

A part ça, dans Java, comme l'absence de type "référence forcément non nulle" est une source d'erreurs, il existe des annotations @Nullable et @NotNull. Mais il existe plusieurs implémentations de ces annotations, aucune n'étant l'implémentation standard.
Plus d'infos ici : https://stackoverflow.com/questions/...n-should-i-use.

En C++, par contre, on a la chance d'avoir la distinction entre pointeurs et références. Les pointeurs peuvent être nuls, pas les références.
Avatar de evanboissonnot evanboissonnot - Futur Membre du Club https://www.developpez.com
le 24/07/2017 à 7:28
Bonjour tout le monde

En lisant le sujet, c'est exactement ce que je me suis dit : la personne mélange les différents niveaux de documentation.

De plus, quand on est sur la documentation grâce aux commentaires de code, pour moi, il ne s'agit pas de documentation. Il s'agit de complément d'information pour des personnes qui relisent notre code.

Mais pourquoi commenter ? Un commentaire n'est pas en soi important.
Pourquoi ne pas créer des méthodes avec des noms clairs ? Pourquoi ne pas créer des classes avec des noms compréhensifs ?

En fait coder, ça peut s'apparenter à créer un nouveau langage : si tu n'as pas le traducteur, il faut aider les autres personnes pour lire ce que tu as écris.

En revenant sur la documentation technique, elle apporte un vrai plus, même si selon moi, c'est une erreur de faire tout le travail à la main. Il existe assez d'outils pour auto-générer une bonne partie de la documentation technique.

La documentation fonctionnelle, si elle est bien organisée, en lien avec la documentation technique et le code (norme organisationnelle) va permettre à tout le monde de comprendre ce que l'on fait dans le code.

A plus
Evan
Offres d'emploi IT
Ingénieur système et réseau h/f
Meetic - Ile de France - Paris (75000)
Integrateur applicatif H/F
Lyon Tertiaire ADEQUAT - Rhône Alpes - Lyon
Référent technique java/jee h/f
BULL FR - Provence Alpes Côte d'Azur - Marseille (13000)

Voir plus d'offres Voir la carte des offres IT
Contacter le responsable de la rubrique Accueil