Code annoté
Mer 20 mars 2013
Il y a une tendance qui a la fâcheuse tendance à me brouter la nouille plus que de raison : au lieu de fournir une documentation ou un tutoriel concernant l'utilisation d'une bibliothèque ou d'un programme, les développeurs renvoient les futurs potentiels utilisateurs de leurs oeuvres à leur code source. Commenté, certes, mais au simple code source.
C'est à la mode. Et ça me démoralise.
La première fois que j'ai vu ça, c'était pour CoffeeScript. Bon, heureusement, ce n'est pas la seule source de documentation. Mais de plus en plus de projets ont embrayé le mouvement. Il arrive quand même qu'on ait une vague idée de l'utilisation qu'on peut faire de l'outil en question, parce qu'on aperçoit un semblant d'exemple d'utilisation, plus ou mois complet.
La goutte d'eau qui a fait déborder mon vase, c'est la liste absolument délirante de "tutoriels" pour backbone JS. Tu peux scroller un moment, tu n'auras pas de tutoriel avant la 10ème page écran. Tout le reste, ce ne sont que des applis, toutes faites, du sol au plafond, plutôt bien commentées. Et souvent, un lien vers la fameuse page "Annotated Source", avec, en regard, le code et ses commentaires.
Ceci n'est PAS la solution. Je ne peux PAS apprendre en lisant un listing complet, de A à Z, avec tous les éléments placés, les modèles, les vues, l'interface etc. Pour la bonne et simple raison que l'application est COMPLÈTE. Finie, done, achevée, totale. Et donc, MORTE.
La métaphore de la cuisine me poursuit : ce que tu me donnes, quand tu me jettes ton "annotated source" à la figure, c'est un plat surgelé, industriel. Je lis l'étiquette, je connais tous les ingrédients, mais je n'ai aucune idée de comment tu as pu les mélanger, les cuire, les incorporer, dans quel ordre ?
Que puis-je en faire si je n'ai rien fait par moi-même ? Que puis-je apprendre si je n'ai pas ÉTAPE PAR ÉTAPE suivi la recette, fait, expérimenté, adapté le programme à mon goût et mon envie ? Il arrive très souvent pour ne pas dire systématiquement que lire un code ligne à ligne n'aie aucun intérêt : il faut souvent partir de la fin, la dernière ligne qui a un "main()" qui appelle les modules un à un. Mais en haut du code source, y'a les imports de modules externes, utilisés en-dessous, etc. Bref : tu me donnes la recette dans le désordre.
Que faire si ton ingrédient ne me plaît pas ? Il n'est pas dans mon menu perso ? ok ! je le remplace par autre chose, tout est bon pour moi. C'est souvent ce que je fais avec un exercice "imposé", s'il veut gérer des employés et des services, j'en fais un gestionnaire de bouteilles de bière (par catégories), par exemple.
On fait ça tout le temps, quand on programme - hormis pour les purs algorithmes, le reste des ingrédients, c'est à ma sauce, avec ce que j'ai sous la main, avec mon idée.
Dans un vrai tutoriel, on voit se composer le plat, peu à peu. Il grandit, il évolue, on voit peu à peu, pas à pas, se développer les modules... Et parfois, on montre une manière de faire au début, et puis... scratch that, voilà la meilleure manière, celle que tu retiendras toute ta vie de développeur parce qu'elle allège ton code, qu'elle utilise les API de plus haut niveau.
Nous avons la chance de pouvoir faire, défaire, refaire, nous exercer mille fois, en utilisant des méthodes différentes. Certains participent même à des code kata où l'objectif est de faire, refaire, refaire plusieurs fois le même programme jusqu'à ce qu'il soit parfaitement exécuté. Pas de lire, relire, relire le même code source en s'imprégnant de ses commentaires.
Le code annoté peut avoir son utilité pour ceux et celles qui ont envie de regarder sous le capot, dans les entrailles d'une application ou une bibliothèque tierce, mais ce n'est pas et ce ne sera jamais un outil d'apprentissage "primaire". C'est un outil avancé, pour les aguerris, ceux qui maîtrisent déjà un minimum.
Par pitié, la prochaine fois que tu veux réellement documenter un projet, fournis une vraie doc, un vrai document d'usage de ta bibliothèque. Et si vraiment tu y tiens, fournis aussi un listing annoté, mais n'appelle pas ça "tutoriel".
Sinon, je tue un moineau.