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 2017-07-22 19:46:14, 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 ?
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 ?
Voir aussi :
-
CodeurPlusPlusEn attente de confirmation mailMais 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.le 25/07/2017 à 13:13 -
GulienMembre habitué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.le 24/07/2017 à 17:41 -
TiranusKBXExpert confirmérenseigner donc la date de naissance et une fonction vous retourneras l'age en fonction de la date du jourle 24/07/2017 à 20:06
-
Matthieu VergneExpert éminentSujet 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 :
mais pas avec cela :
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 :
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 :
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 :
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 :
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 à :
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.
Code comments document the why, not the how.
- 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.
Tout de suite après, il affirme que :
[Code comments and object names] are effectively inverses of each other.
[Documentation and code] are effectively inverses of each other.
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.
Once you start writing quality code comments, you can use a tool like Sphinx or Javadoc to include them in your documentation.
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
Il poursuit :
Documentation is for every possible user.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?
- 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- 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.
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.
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 : 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
32public 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); }
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.le 29/07/2017 à 20:29 -
TiranusKBXExpert confirmé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éle 24/07/2017 à 17:00 -
HaraKityNouveau membre du ClubIl 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."le 25/07/2017 à 16:37
-
Matthieu VergneExpert éminentIl 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.
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.le 05/08/2017 à 15:18 -
martopiocheMembre éclairé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 )…
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"…
Quand on regarde la source, non, c'est le relais sur Developpez qui est mal rapporté.le 23/07/2017 à 18:57 -
Luckyluke34Membre émériteSaying that variable names are the only documentation neededPeople who believe in a world of self-documenting code
La position des défenseurs du code auto-documenté, ce n'est pas de ne jamais écrire de commentaires mais de l'éviter quand ce n'est pas nécessaire, par exemple quand ce qu'on veut communiquer peut passer par un nommage adéquat (d'une variable, classe, etc.) Parce que les commentaires, c'est très vite obsolète, ça peut se retrouver très loin du code d'origine, ça échappe aux outils de refactoring, etc. Mais parfois, il est évidemment indispensable de commenter.A vast majority of software users are not people who develop that software. Saying that variable names are the only documentation needed means that only people who read your code can use it.le 27/07/2017 à 13:33 -
Matthieu VergneExpert éminentDu 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.le 15/08/2017 à 14:39