Vous êtes nouveau sur Developpez.com ? Créez votre compte ou connectez-vous afin de pouvoir participer !

Vous devez avoir un compte Developpez.com et être connecté pour pouvoir participer aux discussions.

Vous n'avez pas encore de compte Developpez.com ? Créez-en un en quelques instants, c'est entièrement gratuit !

Si vous disposez déjà d'un compte et qu'il est bien activé, connectez-vous à l'aide du formulaire ci-dessous.

Identifiez-vous
Identifiant
Mot de passe
Mot de passe oublié ?
Créer un compte

L'inscription est gratuite et ne vous prendra que quelques instants !

Je m'inscris !

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

141PARTAGES

17  0 
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 ?

Une erreur dans cette actualité ? Signalez-le nous !

Avatar de CodeurPlusPlus
En attente de confirmation mail https://www.developpez.com
Le 25/07/2017 à 13:13
Citation Envoyé par martopioche Voir le message
(...)
L'idéal n'est-il pas d'avoir une approche que la POO utilise, un concept de fou : l'encapsulation… (...)
Mais on n'a pas attendu la POO pour faire de l'encapsulation...

Je me demande bien sur quel genre de projet tu travailles pour être à ce point limité à une seule manière de concevoir le développement ?

Et cette seule manière est totalement dans l'air du temps...

C'est pour cela que tu n'arrives pas à convaincre tout le monde malgré la "masse" de ton argumentation :
il y a ici des intervenants qui ont vu passer plusieurs "airs du temps". Par exemple pour les commentaires : à une époque on nous disait qu'il fallait absolument qu'il y ait plus de commentaires que de code ; puis on a voulu nous faire croire que mettre des commentaires était nécessairement la preuve qu'on code comme un porc, etc, etc.

Quand on a vu passer plusieurs "airs du temps", on fait confiance à son expérience, et à celle des autres et à leur variété.

C'est plus sain qu'agiter des "bonnes pratiques" comme le ferait un fanatique religieux.
7  0 
Avatar de TiranusKBX
Expert confirmé https://www.developpez.com
Le 24/07/2017 à 20:06
renseigner donc la date de naissance et une fonction vous retourneras l'age en fonction de la date du jour
5  0 
Avatar de TiranusKBX
Expert confirmé https://www.developpez.com
Le 24/07/2017 à 17:00
Citation Envoyé par Nebulix Voir le message

Citation Envoyé par 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é
4  0 
Avatar de Gulien
Membre habitué https://www.developpez.com
Le 24/07/2017 à 17:41
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.
4  0 
Avatar de HaraKity
Nouveau membre du Club https://www.developpez.com
Le 25/07/2017 à 16:37
Il y a une citation (je ne sais plus quel en est l'auteur) qui dit :

"Entre ce que je pense, ce que je veux dire, ce que je crois dire, ce que je dis, ce que vous voulez entendre, ce que vous entendez, ce que vous croyez en comprendre, ce que vous voulez comprendre, et ce que vous comprenez, il y a au moins neuf possibilités de ne pas se comprendre."
Avec les programmes informatiques, il doit être possible de doubler le nombre de possibilités de ne pas se comprendre
4  0 
Avatar de Matthieu Vergne
Expert éminent https://www.developpez.com
Le 29/07/2017 à 20:29
Sujet qui fait suite à celui-ci. C'est bien, en 3 jours on a 2 articles sur 2 sujets similaires mais complémentaires. L'un sur l'utilité des commentaires, l'autre sur l'utilité de la documentation, les deux par rapport au code. De quoi prendre le temps d'expliquer les différences. J'ai donné mon avis pour la comparaison code-commentaire, voilà donc celui pour la comparaison code-documentation.

L'ennui est que la traduction de la source laisse à désirer et, du coup, il y a des choses qui portent à confusion. Je vais donc d'abord commenter l'article DVP de manière isolée, et ensuite la source elle-même.

L'article DVP

On construit ici sur des termes communs mais utilisés de manière non commune. En l'occurrence, je suis tout à fait d'accord avec ceci :
Citation Envoyé par Patrick Ruiz Voir le message
[un commentaire] 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.
mais pas avec cela :
Citation Envoyé par Patrick Ruiz Voir le message
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 ».
Autrement dit, on parle de la structure du code comme d'une documentation, alors qu'en général on parle de documentation pour parler de textes autres que le code. On introduit donc un amalgame entre le code et la documentation, qui amène à une incohérence notoire : dès lors que la structure du code est en elle-même de la documentation, un code ayant toujours une certaine structure, il est par définition toujours documenté, et donc autodescriptif au moins dans une certaine mesure. On ne peut donc pas parler de mythe de l'autodescriptif, ça n'a pas de sens.

Je note par ailleurs que la critique cible les arguments parlant du fonctionnement de la fonction :
Citation Envoyé par Patrick Ruiz Voir le message
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.
Et ils ont raison ! En effet, on peut séparer une tâche en trois phases :
1. L'occurrence d'un contexte (Quand)
2. qu'on transforme au travers d'un moyen (Comment)
3. pour atteindre un objectif (Pourquoi)

Le code concerne uniquement le moyen. Il décrit comment passer du contexte à l'objectif. S'il est autodescriptif, cela veut dire qu'en connaissant le contexte et l'objectif, lire le code suffit à comprendre le moyen utilisé pour passer de l'un à l'autre. Un code qui n'est pas autodescriptif nécessite une description supplémentaire pour comprendre ce moyen, typiquement en annotant le code au fur et à mesure de son déroulement. Ces annotations, qui sont donc par définition facultatives car réécrivant le code dans un autre langage sans rien changer audit code, sont ce qu'on appelle des commentaires. Code comme commentaires concernent donc le moyen, et uniquement celui-ci.

Pour le reste, à savoir le contexte d'utilisation et l'objectif visé par la fonction, il s'agit de la documentation, dans un sens plus usuel que celui utilisé dans l'article, à savoir une description à destination des utilisateurs de la fonction. Elle permet de décider de la pertinence de la fonction pour le contexte auquel on fait face et l'objectif qu'on souhaite atteindre. Lire la documentation doit suffire pour juger la pertinence de la fonction, indépendamment de son fonctionnement.

Or, ce que l'article critique, c'est que non, il ne suffit pas d'avoir le code pour comprendre le fonctionnement. Mais ce fonctionnement est décrit par le code et ses commentaires, pas par la documentation de la fonction (au sens usuel du terme, pas au sens ambiguë de l'article) qui elle se concentre sur les contextes d'application et les objectifs. Donc pour comprendre le fonctionnement, il faut avoir le code et les commentaires. Sauf que voilà, l'article précise bien que les commentaires ne doivent concerner que "le pourquoi et non le comment", ce qui revient à dire qu'on ne parle en fait pas du fonctionnement dans ces commentaires. Je suis tout à fait d'accord sur ce dernier point : si le code est bien fait, nul besoin de se répéter au travers de commentaires. Mais si on en vient là, alors le fonctionnement n'est décrit, au final, que par le code source. Et c'est là où le raisonnement tombe, parce que l'article amalgame documentation et code :
Citation Envoyé par Patrick Ruiz Voir le message
« 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 ».
Chercher à comprendre le fonctionnement de la fonction n'a aucun intérêt pour un utilisateur, qui veut avant tout connaître les contextes d'utilisation et ce que permet la fonction, autrement dit ses objectifs. Lire le code n'a donc aucun intérêt pour un utilisateur, dès lors que la documentation (au sens usuel) est bien faite. Mais comme on confond ici documentation et code (notamment les conventions de nommage), on amalgame tout naturellement usage et fonctionnement. Et c'est là l'erreur. En l'occurrence :
Citation Envoyé par Patrick Ruiz Voir le message
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.
Non, car les personnes aux compétences limitées (on ne va pas dire sans, sinon elles n'ont rien à faire là) ne sont en effet que de simples utilisateurs, et n'ont donc aucun intérêt à lire le code (et ses commentaires éventuels). Seule la documentation (au sens usuel) doit les intéresser.

Oui, la documentation s'adresse aux utilisateurs de tous bords. Mais oui, aussi, le code seul permet de comprendre le fonctionnement (s'il est bien fait). L'erreur se situe sur l'amalgame entre fonctionnement et usage, favorisé par l'amalgame entre code et documentation.

Mais ce n'est pas la seule erreur. On en a une autre de taille : l'amalgame entre profession et formation, ou code de production et code de présentation. Si on prend 2 fonctions traitant le même contenu, mais dans des contextes ou à des fins différentes, se serait une erreur de débutant que de les utiliser toutes les deux de la même manière. Erreur d'autant plus favorisée que les deux fonctions ont le même nom. Pour autant, cela resterait bel et bien deux fonctions différentes à utiliser différemment. C'est pourtant l'erreur de l'article ici : partant du principe qu'on a du code, on amalgame le code utilisé dans un contexte de production et celui utilisé dans un contexte de formation. Cela se sent déjà quand on parle de "personnes sans compétences en programmation", mais d'autant plus quand on parle de tutoriels :
Citation Envoyé par Patrick Ruiz Voir le message
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.
Ces tutos, ou codes de présentation, visent à illustrer l'utilisation du code de prod. Ils peuvent être extraits du code de prod, mais ce n'est pas nécessaire. Le fait qu'ils le soient permet d'avoir une formation dédiée au projet, plutôt que quelque chose de plus générique, mais comme les exemples utilisés ne concerneront que quelques cas, il faudra forcément savoir généraliser pour pouvoir traiter le reste de l'application. C'est donc un plus, mais pas une nécessité.

La vrai nécessité est que ces codes de présentation, à contrario du code de prod, sont destinés à être lus par des gens qui n'ont pas forcément les compétences suffisantes pour comprendre le code, à contrario du code de prod qui est censé être géré par des gens qui ont au moins ces compétences. C'est de par cette différence d'objectif que les codes de présentation doivent être commentés (et non documentés). Partir du principe que le code de prod doit être commenté comme un code de présentation ne se justifie que si on accepte que des gens incompétents mettent les mains dans le code, ce qui est de toute évidence incohérent. C'est partir du principe qu'un projet Open Source sur GitHub par exemple ne devrait pas avoir de site Web dédié illustrant l'usage du code, le code du projet devant être lui-même commenté pour que les "incompétents" puissent s'y retrouver. C'est viser à côté en se donnant un boulot supplémentaire inutile. Il vaudra mieux avoir des codes de présentation dédiés illustrant les cas intéressants de manière succincte, plutôt que de commenter l'intégralité du projet en se disant que n'importe quel bout de code puisse être lu (et jugé) par un incompétent.

Donc encore une fois, oui à :
Citation Envoyé par Patrick Ruiz Voir le message
« Si vous tenez à avoir des utilisateurs pour les œuvres que vous produisez, il va falloir rédiger de la documentation », a-t-il conclu.
mais on enfonce des portes ouvertes car ces critiques se basent sur des amalgames.

L'article source

L'article source, quant à lui, est différent. En l'occurrence, on ne parle pas de code "autodescriptif" mais "auto-documenté" (self-documenting), ce qui est une différence de taille : on parle bien d'un code qui, de par lui-même, fournit la documentation. Dans la partie précédente, j'explique que le code et la documentation sont tous les deux nécessaires car strictement complémentaires, avec le code pour décrire le moyen et la documentation le contexte et l'objectif. Parler d'un code comme auto-documenté est donc, selon mes définitions, effectivement un mythe. La question est de savoir si l'auteur utilise les même. Hélas, ce n'est pas le cas, l'article mentionnant dès le départ qu'il amalgame documentation et commentaires :
This view generally conflates documentation with code comments.
Néanmoins, l'auteur restreint l'usage de commentaires à un but spécifique* :
Code comments document the why, not the how.
Les commentaires dont il parle sont à prendre comme des descriptions de pourquoi tel code a été choisi, et non une simple traduction du code en langage naturel (comment). Je suis tout à fait d'accord sur cette restriction, cependant ce doit être un cas qui arrive rarement : la fonction elle-même dispose normalement d'une documentation (au sens usuel) qui détaille justement le contexte et les objectifs de la fonction. De là, si le code reste clair et bien organisé (et donc relativement court grâce à l'usage de sous-fonctions bien nommées et elle-même documentées), ce genre de commentaires devrait être particulièrement rare, ne concernant que des bouts de code très optimisés pour exploiter au mieux des subtilités du contexte. Cependant, l'auteur n'est pas aussi restrictif quant à ses exemples :
  • Explaining previous approaches that didn’t work
  • Presenting an example usage of the function and example output
  • Explaining trade offs in the current implementation
  • Marking possible improvements (TODOs) in the code
  • Anything else you’d like to communicate with someone reading or developing the code
  • OK, mais plutôt que donner les cas précédents qui n'ont pas fonctionner, donner uniquement les contraintes déduites de ces erreurs.
  • Un exemple d'utilisation par exemple ne répond à aucun pourquoi, donc ça n'a rien à faire là. C'est de l'ordre du code de présentation, voire de la documentation, et non du commentaire. Mais comme il amalgame documentation et commentaire, ce n'est pas complètement incohérent au premier abord, mais au final ça montre bien qu'on ne sait pas tout à fait sur quel pied dancer.
  • Leçon tirée, donc oui.
  • Je ne traite pas les TODO comme de simples commentaires car ils s'exploitent dans le processus de développement. J'ignore donc ce point là.
  • Complètement faux : tout commentaire est écrit parce qu'on estime que ça peut être utile. On ne peut pas commencer par dire qu'un commentaire se limite à tel type de contenu pour ensuite dire qu'on peut y mettre tout ce qu'on veut. L'auteur n'est ici pas cohérent.

On voit donc que l'auteur ne maîtrise pas tout à fait ses propres recommandations. L'amalgame documentation/commentaire y a d'ailleurs son impact.

Il annonce aussi que* :
Object names document the how, not the why.
Oui, mais ce ne sont pas les seuls : les noms des objets, les noms de méthodes, mais aussi la structure du code elle-même décrit le comment. C'est le code dans son intégralité qui, parce qu'il utilise tels termes de telle manière, décrit le fonctionnement du processus implémenté.

Tout de suite après, il affirme que :
[Code comments and object names] are effectively inverses of each other.
Si on s'en tient à ses deux affirmations, c'est logique, mais on a vu que ses définitions laissent à désirer niveau rigueur. Cependant, si on s'acquitte de son amalgame entre documentation et commentaires, et qu'on étend la deuxième affirmation à l'ensemble du code, on peut reformuler ainsi :
[Documentation and code] are effectively inverses of each other.
et là je tombe entièrement d'accord, car la documentation explique le contexte et le pourquoi, alors que le code décrit le comment, les deux étant strictement complémentaires et nécessaires. On pourrait dire qu'ils sont aussi suffisants d'un point de vue formel (i.e. pas besoin de plus pour créer les tests en théorie), mais il sera facile de trouver d'autres choses utiles à y ajouter pour des raisons pratiques (e.g. les tutos).

Donc, si on corrige au fur et à mesure, je peut tomber d'accord, l'ennui étant qu'il continue de construire sur son amalgame :
An argument against comments is an argument against communication.
Je suis d'accord quand on parle de documentation au sens usuel, mais pas de commentaires. En l'occurrence :
Once you start writing quality code comments, you can use a tool like Sphinx or Javadoc to include them in your documentation.
On parle là d'outils générant de la documentation au sens usuel, à savoir du texte sans code (HTML, LaTeX, plain text, etc.). Or, un commentaire au sens usuel (à l'intérieur d'une implémentation) est normalement associé à un bout de code au sein d'une fonction, pas à la fonction entière, et n'a donc aucun sens sans le code associé. Cela vient donc contredire les exemples donnés par l'auteur, qui parle de commentaires utiles pour celui qui lit ou change le code : sans le code auquel il se rattache, le commentaire n'a plus beaucoup de sens. On parle donc bien de faire de la documentation, et non des commentaires. Encore une fois, l'amalgame ici n'est pas justifié, et au contraire introduit une confusion, voire une erreur, quant à l'usage des outils cités. Oui c'est juste si on parle de documentation, mais pas avec des commentaires.

Le pire est qu'il ne reste même pas constant sur son amalgame, car dans sa seconde section il titre :
Documentation is more than code comments
Désormais, on n'amalgame plus les deux. Les commentaires sont un type particulier de documentation seulement. Donc si avant on parlait de commentaires, on ne parlait pas de la documentation dans son ensemble ? Sauf que du coup, les points où ça faisait sens quant on interprétait "comments" comme "documentation" ne sont même plus possibles. On détruit à petit feu les fondations, pourtant déjà bancales, sur lesquelles s'appuyait le raisonnement tenu jusque là...

Il poursuit :
Documentation is for every possible user.
Oui la documentation (au sens usuel) est faite pour toute usager potentiel, mais un commentaire dans du code n'est fait que pour le codeur qui ira juger/modifier le code (le comment), et non le simple usager (qui se concentre sur quand et pourquoi l'utiliser).

I have a few rhetorical questions about this philosophy:
  • Where does the tutorial go in your self-documenting code?
  • How do you put installation instructions in your variable names?
  • How many users does your self-documenting code have?
C'est là que le second amalgame est fait, entre code de production et code de présentation :
  • Le tuto n'a rien à faire dans un code de production. Ça a un rôle d'introduction et de formation, et donc doit se trouver à part pour être utiliser avant de mettre le nez dans le code de prod.
  • Les instructions d'installation n'ont encore une fois rien à voir. Il s'agit de l'usage de la lib, ce qui se place dans la documentation de celle-ci, et non pas dans la documentation d'une fonction et encore moins dans des commentaires. Critiquer les noms de variables n'a donc aucun sens, car leur ajouter un commentaire ou même une doc ne résoudra pas le problème non plus.
  • Là, on touche avant tout à l'ego du codeur, la question étant juste hors sujet. Il s'agit de connaître les types d'utilisateurs pour établir la documentation en conséquence, mais là on peut prendre 2 perspectives : les utilisateurs potentiels et les utilisateurs ciblés. Dans le premier cas, l'ennui est que ça peut être n'importe qui, donc on pourra faire tout ce qu'on veut, on pourra toujours trouver des exemples d'utilisateurs non satisfaits par la doc fournie, c'est donc un cas d'idéalisme prononcé. Le second cas, par contre, c'est au responsable du code de le décider : il n'a pas à se sentir coupable si certains utilisateurs potentiels ne sont pas couverts, tout simplement parce qu'il ne l'a pas prévu comme cela. D'autres pourront éventuellement aider pour compléter, mais certainement pas lui reprocher de ne pas couvrir tel ou tel type d'utilisateur. Tout du moins, pas sans lui faire admettre que ça serait utile et l'aider à obtenir les moyens de le faire (i.e. participer).


En bref, l'auteur a quelques idées tirées de bonne pratique, mais n'a à mon sens pas encore la compréhension nécessaire pour en faire un tout cohérent, car s'appuie sur des amalgames en générant d'autres, inutiles voire problématiques.

* Je déplore qu'il parle de documenter (anglais : documents) plutôt que de décrire (anglais : describes), car ça favorise l'amalgame documentation/commentaire qui au final aurait très bien pu être évité.

Les réponses du fil

Citation Envoyé par koyosama Voir le message
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

  • Mauvaises excuse, ce n'est pas qu'on n'a pas le temps, mais qu'on a décidé de consommer le temps sur la quantité plutôt que la qualité.
  • Ça c'est juste, tant que ça reste honnête : c'est parce qu'on a pris le temps de faire un code lisible que les commentaires deviennent superflus. La documentation par contre est toujours nécessaire, ne pas la confondre avec les commentaires comme le fait Holscher, sinon on n'y arrive plus.
  • Hors sujet : on parle de nouveaux internes, pas d'utilisateurs externes, or c'est là le sujet de l'article.


Citation Envoyé par martopioche Voir le message
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é…
Non, l'auteur d'origine parle des différents niveaux mais les mets effectivement ensemble. Ce n'est pas juste mal rapporté sur DVP, c'est l'article d'origine qui mélange tout dès le départ. Pour les commentaires et la doc, il le dit même explicitement dès les premières ligne. Pour les tutos, il fait comprendre qu'il faut bien les intégrer quelque part, or avec un post qui se concentre sur "il faut de la doc", tu en tires qu'il faut mettre les tutos dans la doc. Il confond tout.

Citation Envoyé par martopioche Voir le message
Mon dernier exemple : écrire un programme qui demande l'âge du capitaine et l'affiche, mais indique que ce n'est pas possible si il est mineur ou à la retraite SAUF si la question est posée entre 1939 et 1945 où on suppose qu'il peut être mobilisé…
En Java ça te va ?
[spoiler]
Sur la seule base de ce que tu donnes, un design fiable est une classe abstraite qui utilise une API spécifique à son traitement. L'implémentation des cette API nécessite un échange constructif pour préciser les termes et choisir les références à exploiter.

Code : Sélectionner tout
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
public abstract class MartopiocheChallenge implements Runnable {

	@Override
	public void run() {
		AgeCapitaine age = demanderAgeCapitaine();
		if (entre1939et1945()) {
			afficher(age);
		} else {
			if (age.deMineur()) {
				throw new RuntimeException("Impossible, il est mineur.");
			} else if (age.deRetraité()) {
				throw new RuntimeException("Impossible, il est retraité.");
			} else {
				afficher(age);
			}
		}
	}

	public static interface AgeCapitaine {

		boolean entreAnnées(int année1, int année2);

		boolean deMineur();

		boolean deRetraité();
	}

	protected abstract AgeCapitaine demanderAgeCapitaine();
	protected abstract boolean entre1939et1945();
	protected abstract void afficher(AgeCapitaine age);
}
[/spoiler]

Citation Envoyé par cedric57 Voir le message
Moi perso dans la plupart des cas…je comprendrai plus vite le code en le faisant fonctionner avec un débogueur ou encore en ajoutant des messages de log.
Voilà l'exemple type du gars qui se plante lamentablement à l'examen d'info : manque de bol, le script formate ton disque. Il aurait peut-être fallu le comprendre avant de l'exécuter.
4  0 
Avatar de Matthieu Vergne
Expert éminent https://www.developpez.com
Le 05/08/2017 à 15:18
Citation Envoyé par Mat.M Voir le message
en principe la logique voudrait que dans un code source on ne déclare pas de méthode d'une classe setAgeCapitaine car un capitaine c'est un type/une propriété bien particulier
Il faut déclarer une entité/classe humain/client/administré qui est bien plus "générique" que capitaine.
Il ne faut pas forcément. Tout dépend du besoin. Ontologiquement parlant, ce que tu dis se justifie, mais ce n'est pas systématiquement nécessaire en pratique. Tout dépend de l'usage qui en est fait. Le générique permet la réutilisation, plus c'est générique et plus on pourra l'utiliser dans des contextes différents, mais ça impose un design qui ne permettra pas certaines optimisations. Après il y a deux approches : tu démarres générique et swap sur un design plus optimisé plus tard quand nécessaire, où tu design selon tes besoins actuels et fait plus générique plus tard si tu prévois une réutilisation ailleurs.

Citation Envoyé par Mat.M Voir le message
L'intérêt de l'informatique c'est de pousser le niveau d'abstraction le plus haut possible et créer le plus de "généricité" possible.
Ensuite avec les mécanismes de la POO on peut descendre de niveau et créer des types particuliers notamment grâce à l'héritage.
Pas du tout d'accord. On peut le faire mais ce n'est pas le but, ça a un impact de faire du générique. J'ai personnellement une vision orientée très générique, mais je participe à un projet de métaheuristiques où l'optimisation est importantes, et j'admets tout à fait que cette vision générqiue ne se justifie pas tout le temps. On touche justement aux ontologies, qui en informatique ne visent pas à identifier LE meilleur modèle conceptuel. On parle toujours d'un consensus entre les acteurs concernés, donc en fonction du métier et des besoins. S'il est vrai qu'il y a des ontologies fondamentales, style Dolce et la suite UFO, Dolce s'appuie sur une vision cognitive pour le Web sémantique, et si UFO vise l'universalité, je te met au défi de commencer à parler de substance individuals, trope individuals et events dans ton code. Ce sera peut-être très robuste, mais pas super compréhensible pour le codeur moyen. Faire du générique, ce n'est pas un vœu pieu, mais une question de besoin. Il s'agit de ne pas faire du tout générique ni du tout optimisé, ce serait là l'erreur.
4  0 
Avatar de Matthieu Vergne
Expert éminent https://www.developpez.com
Le 15/08/2017 à 14:39
Citation Envoyé par Mat.M Voir le message
oui mais qu'est-ce qui relève du générique et qu'est ce qui relève du spécifique ? Zatize ze questionneu
Du générique, c'est du commun. C'est du code factorisé pour réutilisation. Si tu fais une bibliothèque, a priori tu cherches à couvrir un maximum de cas, et donc tu essayes de faire au plus générique pour éviter d'oublier des cas pertinents. C'est là que tu prend une approche top-down : tu pars de concepts généraux que tu essayes d'implémenter, en fournissant les outils nécessaires pour faciliter l'application à des cas spécifiques. Si tu ne cherches à développer que du code interne, là c'est avant tout du bottom-up : tu factorises du code existant. L'approche générique est utile aussi, car tu peux investir un peu plus de temps au départ pour en gagner par la suite, mais si tu ne maîtrises pas le domaine mieux vaut ne pas tenter le générique d'emblée, c'est prendre le risque de faire une oeuvre d'art théorique sans intérêt pratique (un paquet de mes projets persos sont comme ça, c'est sympa pour réfléchir et se faire la main, mais à part ça...).

J'ai une série de posts en préparation sur la programmation générique, mais je sais pas trop quand ça sortira (c'est plus de l'ordre du bouquin que du 2-3 posts). M'envoyer un MP pour accéder aux brouillons.
3  0 
Avatar de martopioche
Membre éclairé 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é.
2  0 
Avatar de martopioche
Membre éclairé https://www.developpez.com
Le 24/07/2017 à 14:26
Citation Envoyé par foetus Voir le message
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 ?

Citation Envoyé par Pyramidev Voir le message
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
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
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 ?

Citation Envoyé par evanboissonnot Voir le message
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é…
2  0