Discussion :

[koyosama]

C'est bien joli les démonstrations scientifiques à base de séries télé et de stats linkedin mais je ne vois toujours pas en quoi des banques auraient le droit de faire n'importe quoi avec l'argent des autres et pourquoi en plus on devrait les plaindre quand ils doivent payer quelques développeurs pour gérer l'an 2000 ou les taux d'intérêt négatifs.

Le but c'est de donnes une explications scientifiques. En plus, une explication scientifiques dans le domaine financier ... . Si le monde etait vraiement regi par la logique, on aurait jamais ete dans ce merdier et le metier d'assistance social n'existerait pas. Sans compter que tu serais remplacer par un robot. Si tu veux, tu peux les arreter, je te regarde avec un pop-corn a la main.
Et j'ai pas dit que j'etais pour eux ou pour les banques, faite un peu attention a ce que j'ecris. J'ai dit que dans le monde actuel, on a perdu nos c***** face au banques et comme tu l'as dit pour le bug de l'an 2000, on a pas le choix, on doit payer pour la bourde des banques.

Apres attention le but des extraits de series, c'est juste pour un apercu plus visual que de citer un livre d'un auteur inconnu ou oublie depuis le lycee au fin fond de votre bibliotheque ou de votre voisin pour expliquer une notion aussi vieux que le monde. Une serie n'est pas different d'un livre, sa permet de montrer un point de vue tout en se diversant. Si je devais rigoler a chaque fois je lis Jules Vernes. On irait pas loin dans notre reflection. Sinon je me foutrais de tous les gens qui sont dans le serious gaming ou dans la presentation sous forme de gamification.

[Invité]

Le but c'est de donnes une explications scientifiques. En plus, une explication scientifiques dans le domaine financier ... . Si le monde etait vraiement regi par la logique, on aurait jamais ete dans ce merdier et le metier d'assistance social n'existerait pas.

En fait, c'était de l'humour mon message précédent.

Sans compter que tu serais remplacer par un robot. Si tu veux, tu peux les arreter, je te regarde avec un pop-corn a la main.

Tu ne connais absolument rien de ma vie alors garde tes attaques personnelles.

Et j'ai pas dit que j'etais pour eux ou pour les banques, faite un peu attention a ce que j'ecris. J'ai dit que dans le monde actuel, on a perdu nos c***** face au banques et comme tu l'as dit pour le bug de l'an 2000, on a pas le choix, on doit payer pour la bourde des banques.

Il faudra le dire aux islandais.

Apres attention le but des extraits de series, c'est juste pour un apercu plus visual que de citer un livre d'un auteur inconnu ou oublie depuis le lycee au fin fond de votre bibliotheque ou de votre voisin pour expliquer une notion aussi vieux que le monde.

A oué, on nait tro con pour komprendre six noms, sait sa ?

Une serie n'est pas different d'un livre, sa permet de montrer un point de vue tout en se diversant.

Mais un livre, ça permet d'apprendre le français.

Si je devais rigoler a chaque fois je lis Jules Vernes. On irait pas loin dans notre reflection. Sinon je me foutrais de tous les gens qui sont dans le serious gaming ou dans la presentation sous forme de gamification.

Heu, la femme à Georges Moustaki ?

[Jipété]

[...] faite un peu attention a ce que j'ecris.

Impossible.

Entre la quantité impressionnante de fautes d'orthographe et celle phénoménale des fautes de ponctuation, désolé mais ce que tu rédiges se transforme en charabia incompréhensible, la plupart du temps.

Ou alors il faudrait passer un temps considérable à essayer de décrypter, de deviner ce que tu avais à l'esprit au moment où tes doigts pianotaient sur le clavier, et si ça peut te rassurer (mais moi ça m'effraie), tu n'es pas le seul, loin de là, hélas.

Il y en a même un, récemment, qui a écrit le contraire de ce qu'il voulait dire, tellement l'inculture progresse. Ah ça sera beau, les posts, dans 10 ou 20 ans...

[koyosama]

Impossible.Entre la quantité impressionnante de fautes d'orthographe et celle phénoménale des fautes de ponctuation, désolé mais ce que tu rédiges se transforme en charabia incompréhensible, la plupart du temps..

Je n'ai rien a dire contre sa. Je vais essayer de faire plus d'effort. ^^ Je le montre pas sur mes posts, mais j'essaie vraiment, c'est pas evident pour moi . En plus mixer anglais et francais ne m'aident pas.
Mais l'orthographe et la grammaire ne rende pas les idees fausses :p.

[koyosama]

En fait, c'était de l'humour mon message précédent.
Mais un livre, ça permet d'apprendre le français.

Bizarrement, ce n'est pas que dis mon livre, qui commence par : "The author ...". Tu pourras au Collegiale de France que je suis feignant pour lire en Francais dans un pays anglo-saxon ou dans d'autres pays par ailleurs. Je le nirais pas pour ta complaisance a toi, tes sujets ou encore tes acolytes.
Je le repete encore : La France n'est pas le monde. C'est un peu comme dire que faire de la doc en francais ou coder en francais, fais de toi un meilleur developpeur, ou encore un meilleur developpeur que le reste du monde.

[TJ1985]

Marrant de lire certains. Durant 25 ans j'ai maintenu du code, forcément ancien, non documenté. Et j'ai aussi écrit quelques applications, en divers langages. Conclusion : Le code doit utiliser un nommage clair, c'est impératif. Ensuite, expliquer pourquoi on choisit telle option plutôt que telle autre pour implémenter une fonction/méthode est fondamental. Et ça doit se trouver en tête de fonction, pas quelque part dans une doc perdue je ne sais où.
Donc je suis d'accord avec l'auteur de l'article original. On peut bien sûr préférer une doc structurée, à jour, accessible. Ça doit exister dans certaines structures, bien organisées, où la planification est établie et respectée. En pratique je n'ai jamais rencontré ce type d'environnement.
Enfin, il devrait être possible d'utiliser les liens hyper-textes à partir du source pour remonter à une doc sur un serveur http. Je ne sais pas si ça existe, ce serait incitatif.
Post scriptum : Swift permet un nommage précis des arguments et Apple insiste sur l'utilisation de noms longs et descriptifs à tous les niveaux. Expérience faite, c'est vrai que le système de double nommage externe/interne clarifie le propos lorsqu'il est applicable. Mais on peut toujours écrire

Code :

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

func toto(a b: String)-> String

...

[Cincinnatus]

Si tu as fait un peu fait d'economie, OUI, oui et encore OUI. C'est un peu desolant de voir ce genre de scenario. Mais croire a la bonte du systeme est tres mignon de ta part ^^.

La societe repose sur des piliers importants. Si tu regardes Mr Robots, tu peux voir un apercu de ce que peut arriver au monde sans un systeme monetaire comme les banque. Ou si tu prefere, ouvre un livre d'histoire et ouvre la page entre Antiquite et Moyen-Age. C'est le meilleur exemple.

Ensuite les etats jouent un drole de jeu avec les banques. Que tu le veux ou pas, la banque est un pilier centrale d'une societe, de la democracie et du pouvoir en place. Je pense que t'a vu dans Game of throne que meme les Lanisters sont plier devant la banque. Tu peux faire comme le roi de France et detuire tous les templiers, mais quel source financiere te fera confiance ?

C'est le systeme le plus pervert. Si tu prends pas des extraits de films et de series. Je te ferais reference a la crise de wall street en 1938 qui causera plus tard la deuxieme guerre mondiale.

Alors oui, a moins on a tous les couilles comme les islandais pour emmerder les banques. La banque est loi, la banque est au dessus des etats et la banque peut definir vie ou de mort sur un etat. En plus tu regarde cette etude, tu verras que la France est specialiste dans le monde financier, on est un peu lie avec ce monde la.

Je passerais la discussion sur l'économie, d'autres ont répondu à ce sujet avant moi. Et pour plus d'infos sur ce sujet, on peut toujours voir les économistes atterrés, dont c'est le domaine d'activité http://www.atterres.org

Au niveau historique, quel bel ensemble de fadaises (je reste poli) :
-

ouvre un livre d'histoire et ouvre la page entre Antiquite et Moyen-Age. C'est le meilleur exemple.

Et on y trouve quoi ? En général, on fixe le changement au Vème siècle, quand Rome n'est plus officiellement capitale de l'Empire romain d'occident. Mais les historiens remettent actuellement en cause cette distinction. Et pour cause, selon les régions de l'Europe (si on se limite à notre continent), les changements n'ont pas eu lieu de la même façon partout. Les changements de société ont été constants, parfois progressifs, parfois plus brutaux, mais la séparation entre les deux époques est juste artificielle. Tout comme en France on divise le Moyen-Age en deux périodes alors qu'en Allemagne il est divisé en trois périodes.
Ah, et au niveau des monnaies, il y en avait pléthore, dans toute l'Europe, quel que soit le régime dominant.

-

Tu peux faire comme le roi de France et detuire tous les templiers, mais quel source financiere te fera confiance ?

On ne dénombre plus les grands argentiers qui se sont mis au service des rois de France, se sont enrichis, puis ont été déchus, condamnés et spoliés par ces mêmes souverains (et qui exerçaient leur pouvoir). Ils ont toujours été remplacés par d'autres financiers volontaires. L'attrait des honneurs et des gains, sans doute...

-

Je te ferais reference a la crise de wall street en 1938 qui causera plus tard la deuxieme guerre mondiale.

Euh, dans quel monde parallèle ?? Wall Street, c'était 1929, et pour faire court, le problème est plutôt à voir du côté des dommages de guerre dus par l'Allemagne pour 14-18 et les dévaluations puis la ruine du pays. Bon, et aussi l'absence de contre-pouvoir européen lors de son réarmement...
(Un bon roman sur les années 30 en Allemagne : https://fr.wikipedia.org/wiki/La_mort_est_mon_métier)

[deuz59]

Impossible.

Entre la quantité impressionnante de fautes d'orthographe et celle phénoménale des fautes de ponctuation, désolé mais ce que tu rédiges se transforme en charabia incompréhensible, la plupart du temps.

Ou alors il faudrait passer un temps considérable à essayer de décrypter, de deviner ce que tu avais à l'esprit au moment où tes doigts pianotaient sur le clavier, et si ça peut te rassurer (mais moi ça m'effraie), tu n'es pas le seul, loin de là, hélas.

Il y en a même un, récemment, qui a écrit le contraire de ce qu'il voulait dire, tellement l'inculture progresse. Ah ça sera beau, les posts, dans 10 ou 20 ans...

Les posts autodescriptifs seraient-ils des mythes ?

[TJ1985]

Impossible.

Entre la quantité impressionnante de fautes d'orthographe et celle phénoménale des fautes de ponctuation, désolé mais ce que tu rédiges se transforme en charabia incompréhensible, la plupart du temps.

Et c'est d'autant plus dommage que le peu de fond qui reste perceptible n'est pas inintéressant. Peut-être un souci de langue maternelle ? On dirait que phonétiquement le scripteur maitrise bien le Français, que ça foire lamentablement à l'écrit...

[Luckyluke34]

Saying that variable names are the only documentation needed

People who believe in a world of self-documenting code

Comme d'hab, la recette d'un bon troll c'est de prendre un propos adverse et de le caricaturer à l'extrême en lui faisant dire ce qu'il n'a jamais dit.

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.

Dans la notion de code auto-documenté, il n'y a jamais eu non plus la volonté de se substituer à une documentation destinée aux utilisateurs (non développeurs). C'est tellement ridicule qu'il faut être tordu ou d'une mauvaise foi sans borne pour le penser.

[martopioche]

Mais on n'a pas attendu la POO pour faire de l'encapsulation...

Sur le plan définition, tout à fait, bien que pour la majorité le principe est associé à la POO. Dans la pratique, écrire une fonction ne consiste pas à faire de l'encapsulation…

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.

Oh, un beau Argumentum ad antiquitatem. Ok.

Pourquoi x, y, z et pas r, g, b ? Je crois qu'il y a trois conventions de nommage des vecteurs pour les shaders.

Et tu va implanter les 3 dans la même classe ?

Si on prend un dictionnaire, alors dico[x] et dico[r] ne pointerons pas vers le même objet à priori

Ah oui…*Ça doit être pas mal à suivre dans le code ça…

et si l'on utilise un dico, l'initialisation est lourde

Ah bon ? Pourquoi ? Plus qu'un objet ?

et rien n'empêche d'ajouter d'autre éléments

Oui, et c'est pas bien ?

Mathématiquement, un vecteur 3d aura trois coefficiants (float ou autre): le premier, le deuxième et le troisième, donc un tableau est bien mieux si l'on ne veut pas d'encapsulation.

Ah mais tout à fait, si au lieu de x, y et z ou r, g et b, tu utilise 0, 1 et 2, un tableau est bien mieux…

Maintenant, sans encapsulation, je n'aurai pas d'opérateurs mathematiques indispensable pour mes vecteurs (additions, multiplication par un scalaire, produit scalaire, produit en croix, normalisation), ni de méthodes (norme, norme au carrée), donc je devrais implémenter de moches fonction à la C

Code :

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

array[3] add(array[3]& bla, array[3]& toto);

Mais…*Si tu a des fonctions, tu a les opérations mathématiques…*En quoi "moches" ?

C'est stupide car avec une classe, je peux ajouter mes méthodes et opérateurs, je peux cacher ma variable en privée. Je peux utiliser mes conventions de nommage xyz et rgb. Clairement se rabattre sur un array ou un dico, n'est pas satisfaisant.

Tu peux oui, lesquelles ? Parce que tu n'avait rien exprimé auparavant…

D'ailleurs, les libs que j'utilises ont toutes une classe vecteur.

Oui, une lib. Une lib est écrite pour répondre à des besoins génériques (du métier) non définis. Enfin, si je suis la même logique, tu utilise bien toutes les méthodes des classes définies par tes libs ?

[martopioche]

Post scriptum : Swift permet un nommage précis des arguments et Apple insiste sur l'utilisation de noms longs et descriptifs à tous les niveaux. Expérience faite, c'est vrai que le système de double nommage externe/interne clarifie le propos lorsqu'il est applicable. Mais on peut toujours écrire

Code :

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

func toto(a b: String)-> String

...

Grand fou, le double nommage à la Apple…*:p

[raphchar]

Et tu va implanter les 3 dans la même classe ?

Et pourquoi pas ?

Ah bon ? Pourquoi ? Plus qu'un objet ?

Bon, ok, si tu écris une fonction f(x,y,z) qui renvoit ton dico initialisé. Mais dans ce cas, tu pers l'intérêt de la POO.

Oui, et c'est pas bien ?

Non, c'est pas bien. Un vecteur 3d est un vecteur 3d, si tu rajoutes des infos comme une 4ème dimension, tu devrais interpréter ton vecteur 3d comme un vecteur 4d et changer le type d'un objet, je ne pense pas que ce soit une bonne pratique. Avec un vecteur 3d, il n'y a pas d'ambiguïté.

Mais…*Si tu a des fonctions, tu a les opérations mathématiques…*En quoi "moches" ?

Tout du moins pas pratique, la POO tu permets d'écrire

Code :

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

vec3 c=a+b

Rien que pour la lisibilité du code, c'est mieux que

Code :

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

dico c=AddVec3Vec3(dico a,dico b)

Tu remarqueras que l'emploi de dictionnaire utilisé pour représenter un vecteur, avec un array, on peut ce contenter de Add, mais ça ne change pas ma remarque sur la facilité de lecture.
Là je ferais la même remarque, ta façon de faire sans déclarer de classe vecteur, ressemble à du C, et n'utilise pas les concepts de la POO.

Tu peux oui, lesquelles ? Parce que tu n'avait rien exprimé auparavant…

Quelles méthodes ? Tout les opérateurs mathématiques auquels on peut penser. Mais je ne comprends pas cette remarque, pourrais-tu la reformuler ?

Oui, une lib. Une lib est écrite pour répondre à des besoins génériques (du métier) non définis. Enfin, si je suis la même logique, tu utiises bien toutes les méthodes des classes définies par tes libs ?

Oui, mais mon point est que ces libs déclarent des classes vecteurs et ne se contentent pas de réinterpréter une structure existante comme vecteur.

Pour résumer ma vision : créer des classes apporte une plus value au code, tout d'abord en lecture et ensuite en fonctionnalité. Se rabattre sur une classe existante, c'est bien, mais pour y rajouter des opérateurs/opérations spécifiques, il me semble indispensable de créer une nouvelle classe.

[martopioche]

Et pourquoi pas ?

Au hasard, parce que pour une question de lisibilité tu ne mixera pas les 3 ?

Bon, ok, si tu écris une fonction f(x,y,z) qui renvoit ton dico initialisé. Mais dans ce cas, tu pers l'intérêt de la POO.

??? En quoi déporter l'initialisation d'un dictionnaire dans une fonction le rend "moins lourd" que de l'initialiser directement ?

Non, c'est pas bien. Un vecteur 3d est un vecteur 3d, si tu rajoutes des infos comme une 4ème dimension, tu devrais interpréter ton vecteur 3d comme un vecteur 4d et changer le type d'un objet, je ne pense pas que ce soit une bonne pratique. Avec un vecteur 3d, il n'y a pas d'ambiguïté.

? Pas d'ambiguïté de quoi ? Si il y a une 4ème dimension, c'est un 4d, ou plutôt, si il n'y en a pas, ce n'en n'est pas…*En quoi c'est ambigüe ?

Tout du moins pas pratique, la POO tu permets d'écrire

Code :

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

vec3 c=a+b

Rien que pour la lisibilité du code, c'est mieux que

Code :

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

dico c=AddVec3Vec3(dico a,dico b)

Tu remarqueras que l'emploi de dictionnaire utilisé pour représenter un vecteur, avec un array, on peut ce contenter de Add, mais ça ne change pas ma remarque sur la facilité de lecture.

Pas certain, en quoi

Code :

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

validate(a + b)

est plus "lisible" pour comprendre ce qu'on manipule que

Code :

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

validate(addVectors(a, b))

??? Ou

Code :

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

let c = a + b

est plus lisible que

Code :

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

let c = addVectors(a, b)

?

Là je ferais la même remarque, ta façon de faire sans déclarer de classe vecteur, ressemble à du C, et n'utilise pas les concepts de la POO.

Quel rapport avec le C ? Alors certes, en C, il est impossible d'utiliser "les concepts de la POO". D'autre part, quel concept ? Celui qui consiste à déclarer des méthodes ? Cela prive-t-il de l'usage de fonctions ?

Quelles méthodes ? Tout les opérateurs mathématiques auquels on peut penser. Mais je ne comprends pas cette remarque, pourrais-tu la reformuler ?

Heu…*un programme informatique est destiné à répondre à un besoin…*Dans ton post d'il y a 4 jours, tu parle juste d'avoir une classe représentant un vecteur plutôt qu'une pair d'entier, à aucun moment tu n'a exprimé un autre besoin que de représenter une pair d'entier et pour ma part, je ne vais pas commencer à faire de la conception de "tout ce que l'on peut penser" sur une simple expression de "représenter une donnée". Ce n'est que le post suivant que tu introduit la notion de shader et uniquement maintenant que tu parle d'opérations entre eux pour aller jusqu'à "tout ce qu'on peut penser"…*La POO n'est pas une poubelle pour l'absence de définition du besoin…

Pour résumer ma vision : créer des classes apporte une plus value au code, tout d'abord en lecture et ensuite en fonctionnalité. Se rabattre sur une classe existante, c'est bien, mais pour y rajouter des opérateurs/opérations spécifiques, il me semble indispensable de créer une nouvelle classe.

Nope ce n'est pas aussi binaire. "Créer une classe" entraine la manipulation d'une notion sous forme d'objet, c'est tout. Une plus value est déduite de la manipulation que tu dois avoir de cette notion. Et je remonte donc à il y a 4 jours, une classe "age", "taille" ou "vecteur3d" qui sert juste à transférer la donnée sous-jacente n'a aucune plus value autre que passer par l'instanciation d'objets afin de faire chauffer les processeurs. C'est une constante sur les 2 posts que je suis depuis quelques jours : tout le monde y va de sa proposition de conception, définir des objets, des injecteurs de dépendances, des factory…*Ah non, ça c'est moi…*Enfin, tout le monde y va d'une conception alors qu'aucun besoin n'est défini…*La plus-value, c'est qu'au final, on a une complexification qui ont au moins l'intérêt de nous garantir du boulôt. Sérieux, un

Code :

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

1
2
3
4
5
ageDuCapitaine = Age.createFromString(input("Quel est l'âge du capitaine ? "))
if 18 < ageDuCapitaine.years < 65:
    print("Le Capitaine a " + ageDuCapitaine.yearsAsString)
else:
    print("Pas possible un capitaine si jeune")

Je ne suis pas certain de la plus-value par rapport à

Code :

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

1
2
3
4
5
ageDuCapitaine = int(input("Quel est l'âge du capitaine ? "))
if 18 < ageDuCapitaine:
    print("Le Capitaine a {}".format(ageDuCapitaine))
else:
    print("Pas possible un capitaine si jeune")

[TiranusKBX]

[...]C'est une constante sur les 2 posts que je suis depuis quelques jours : tout le monde y va de sa proposition de conception, définir des objets, des injecteurs de dépendances, des factory…*Ah non, ça c'est moi…*Enfin, tout le monde y va d'une conception alors qu'aucun besoin n'est défini…*La plus-value, c'est qu'au final, on a une complexification qui ont au moins l'intérêt de nous garantir du boulôt. Sérieux, un[...]

Je propose alors un petit test conceptuel, qui propose le thème? la je voit pas quoi leur donner sans qu'ils me sortent une usine à gaz de 200 pages

[martopioche]

Je propose alors un petit test conceptuel, qui propose le thème? la je voit pas quoi leur donner sans qu'ils me sortent une usine à gaz de 200 pages

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

[cedric57]

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. Ensuite je trouve la doc utile quand le code n'est pas simple à compiler / exécuter…ou encore pour comprendre les workarounds / morceaux de code pas intuitifs.
Sinon j'invite les défenseurs de la doc ultra complète à se poser les questions suivantes:
- Entre doc ultra complète et pas de doc, ne peut-il pas avoir un juste milieu? Cela ne dépendrait-il pas du projet en question?
- Pourquoi les hackers n'ont pas besoin de doc…ni de code pour comprendre comme marche un système avant de le hacker?
- Pourquoi existe-t-il des projets open source conséquents peu documentés mais qui évoluent très bien?
- Le débogueur et l'ajout de message à un code bien écrit ne peut-il pas souvent être un bonne alternative à la doc?
- Quand on est limité par le temps, faut-il mieux moins bien coder ou sacrifier la doc?
- Quand on recrute un développeur peu expérimenté ou peu motivé dans un projet complexe non documenté…le problème est-il vraiment du à un manque de doc? Ce développeur pourrait-il facilement reprendre facilement un autre projet complexe mais bien documenté comme gmail?

[Invité]

Perso, étant un n00b en programmation, j'ai appris en regardant le code des autres et je ne partage pas du tout l'avis de l'article.

Des variables, méthodes et class bien nommées m'ont été 1000x plus utile que les commentaires qui sont une vrai gène pour comprendre le code et la façon de penser de celui qui l'a créé.

Je pars souvent de logiciel open source pour réécrire les miens et mon premier reflex est d'effacer 99% des commentaires qui sont totalement inutile et font perdre un temps fou.

Je ne suis pas un dev pro, juste quelqu'un qui a décidé de s'y mettre parce que j'en avais marre de la pub/flicage/vol de données alors l'argument du "il faut penser au débutant", pour moi, ne tient absolument pas la route.

Au final, je fais ce qui m'a paru le plus facile pour comprendre du code, bien nommer et un minimum de commentaires. Un code bien propre propre est franchement plus agréable et facile à appréhender qu'un truc documenté.

[Matthieu Vergne]

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 :

[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 :

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 :

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 :

« 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 :

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 :

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 à :

« 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

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.

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.

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 ?

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

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);
}

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.

[Bruno PICART]

Eric Holscher, à l'image de nombreux "experts" souvent autoproclamés et auto-congratulés, n'a pas encore compris que c'est le code qui est compilé. Pas les commentaires. Ni la documentation...
C'est grave, Docteur !