Discussion :

[Patrick Ruiz]

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 ?

[TiranusKBX]

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)

[raphchar]

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.

[der§en]

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.

[koyosama]

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 - Visualiser dans une fenêtre à part

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 - Visualiser dans une fenêtre à part

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.

[martopioche]

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"…

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é.

[martopioche]

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…

[foetus]

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

[super_navide]

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.

[Pyramidev]

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.

[evanboissonnot]

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

[MikeRowSoft]

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 ».
[...]
Partagez-vous l’avis de l’auteur sur la portée qu’il attribue à la notion de documentation en génie logiciel ?

Presque tout a fait d'accord. Surtout quand il s'agit d'une "partie" de code à "intégré" dans un projet (ré-utilisabilité, "le comment"). Se code étant lui même un projet complet ayant sa propre documentation et interface de tests/validations ("le pourquoi").

Bien sur "le comment" d'un algorithme (ponctuel dans une méthode), n'est pas "le comment" d'un "projet". Et encore moins justifier "un pourquoi" (la raison de) ...

[martopioche]

Il me semble que les tests unitaires peuvent faire office de documentation

Les tests unitaires sont de la documentation, ils montrent des exemples d'usage des méthodes/fonctions… Mais lorsque tu utilise une lib, tu ne va pas aller te bouffer les tests unitaires pour savoir quelle borne est acceptée dans tes paramètres…

Sérieux, si utiliser une fonction nécessite plus de temps qu'écrire le traitement nécessaire, tu préfère quoi ?

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 […]

Merci mais c'est se focaliser sur un cas particulier et simpliste. Pour ce cas, j'ai simplifié à ce que tout le monde comprends sans considérer le métier (et pour être honnête, ce cas a plus de 10 ans, je ne me souviens plus des détails). Il me semble que tu est intervenu sur le sujet commentaire du code, je reprends l'exemple d'un discutable

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

setAgeCapitaine(int age)

où la proposition était d'utiliser un type signé pour éviter un âge négatif…*Mais l'âge d'un capitaine n'est pas juste positif et négatif…

Après, les conventions ont le défaut d'être des conventions et d'être suivies…*ou pas. Lorsqu'elles sont bien implantées (cas de Python par exemple), ça marche. Mais une convention en vigueur dans une boite, c'est en soi beaucoup plus risqué.

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.

Ce genre de suffixe/préfixe, clairement, non… Les noms de fonctions/variables doivent exprimer ce qu'elles font, pas comment et surtout pas représenter une implémentation technique.

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

getStrudents_canBeNull()

est une aberration de lecture, mais surtout, est une fonction qui a fini par être exposée par la lib (ce n'était pas prévu à l'origine) et l'implémentation a changée, elle ne peut plus être Null… On fait quoi ? On garde un nom qui ne veut rien dire ou on change en informant les 8000 établissements de France qu'ils doivent modifier leurs outils qui utilisent notre lib ?

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

En fait pas du tout, elle fait exactement la distinction entre les différents niveaux : nommage, commentaires, documentation type JavaDoc, PyDoc, DocBocks…, tutos… C'est bien écris dans son post mais très mal rapporté…

[Nebulix]

Ce mec ne confond t'il pas la Documentation utilisateur et la documentation Technique ?

Avec une doc utilisateur qui explique pourquoi sans dire comment et l'autre qui dit comment sans dire pourquoi, il te reste à jongler avec les deux plus le code pour t'y retrouver...

[raphchar]

Merci mais c'est se focaliser sur un cas particulier et simpliste. Pour ce cas, j'ai simplifié à ce que tout le monde comprends sans considérer le métier (et pour être honnête, ce cas a plus de 10 ans, je ne me souviens plus des détails). Il me semble que tu est intervenu sur le sujet commentaire du code, je reprends l'exemple d'un discutable

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

setAgeCapitaine(int age)

où la proposition était d'utiliser un type signé pour éviter un âge négatif…*Mais l'âge d'un capitaine n'est pas juste positif et négatif…

Les puristes te diront qu'il faudrait implémenter une classe age. Ainsi on peut utiliser une panoplie de constructeurs. Ok, ça ne fait que déplacer le problème de l'âge négatif au constructeur Age(int yearsFromBirth); mais là on a un nom bien explicite (et on peut même interpréter un âge négatif comme le temps restant avant de naitre). Mais si l'on revient au problème initial, on peut affirmer, que si le code accepte un âge négatif si on ne le veut pas, c'est un bug, pas un manque de documentation.

[Nebulix]

... si le code accepte un âge négatif si on ne le veut pas, c'est un bug, pas un manque de documentation.

Il n'y a pas très longtemps, les organismes financiers du monde entier ont du faire réécrire leurs logiciels pour prendre en compte les taux d'intérêts négatifs.

[MikeRowSoft]

[...]Mais lorsque tu utilise une lib, tu ne va pas aller te bouffer les tests unitaires pour savoir quelle borne est acceptée dans tes paramètres…[...]

C'est vrai, le type de variable doit être commenté, surtout si cette "variable" est une "class" (instance).

[TiranusKBX]

Ce mec ne confond t'il pas la Documentation utilisateur et la documentation Technique ?

Avec une doc utilisateur qui explique pourquoi sans dire comment et l'autre qui dit comment sans dire pourquoi, il te reste à jongler avec les deux plus le code pour t'y retrouver...

Rien à voir!
La documentation utilisateur c'est: comment utiliser le machin(ça rien à voir avec le code, c'est ne niveau 0 de description d'un programme)
La documentation technique c'est: comment ça fonctionne et structuré

[Gulien]

Pour moi ce n'est pas le code lui-même qui doit être commenté, celui-ci doit effectivement être lisible, ou alors pour donner une indication ponctuelle.
(du style //j'ai utilisé la bibliothèque X par facilité, mais la Y serait plus adaptée pour telles raisons)

MAIS : Un programme doit OBLIGATOIREMENT disposer d'une documentation de son API interne !
Sans ça pour moi, c'est comme si on nous filait Java sans sa doc... Et on devrait deviner comment il fonctionne ... Quelle perte de temps

Et là on se rends compte : Tiens il y a deux méthodes servant à faire le calcul de l'optimisation du temps de transport ... Tiens elles ne font pas les même calculs ... Tiens on l'aurait jamais vu sans une documentation de l'API ... Chacun tapant dans l'une ou dans l'autre grâce à une formidable et désespérée transmission orale.

Perso, je ne suis tombé que dans des boîtes qui "n'avait pas le temps" de rédiger cette documentation. Et je leur en veux terriblement.
Maintenant, soit c'est moi qui crée le logiciel (ça va paraître prétentieux) et je sais qu'elle est bien montée/documentée, soit je fais autre chose (chef de projet, management ...)

mais en aucun cas je pourrais re-bosser pour une boîte qui me dit très orgueilleusement : Pas besoin de doc, de toutes façon ça bouge trop vite, on peut pas la maintenir, et tu peux lire le code !
J’appelle ça
1/ de l'ignorance des bonnes pratiques
2/ De l'irrespect total envers les nouveaux venus
3/ Du suicide à long terme

Oui je suis remonté contre 80% des boîtes de devs Française, qui font de l'amateurisme à ce niveau.

[martopioche]

Les puristes te diront qu'il faudrait implémenter une classe age.

Puriste de quoi ? Parce que les puristes de la POO me diront surtout que si l'objet capitaine a une notion d'âge, celle-ci est définie dans le constructeur puisqu'un capitaine sans âge n'a pas de sens, donc il n'y a pas de méthode setAge.…

Après, celui qui me propose une conception sur ces 3 lignes de commentaire pour me pondre un modèle qui vient complexifier l'ensemble sans apporter de solution, merci, je m'en passe. Car nous sommes d'accord que une classe Age est plus adaptée, mais il faut qu'elle puisse fournir l'âge par une AgeFactory elle même implémentant une AbstractAgeFactory pour prendre en compte les différents types de définition de l'âge. Ainsi, on peut l'injecter dans les CaptainFactory…

Sérieux…*tu propose une classe qui encapsule un entier qui n'apporte aucun contrôle métier pour ce cas là… Oué…

C'est vrai, le type de variable doit être commenté, surtout si cette "variable" est une "class" (instance).

Pourquoi "surtout" si c'est une classe ? N'importe quelle donnée, non ?