- En développement logiciel, il est difficile de passer directement d’un document de conception à une PR propre, car les hypothèses vacillent souvent pendant le codage ; explorer la conception avec du code jetable peut donc être plus rapide
- L’idée proposée consiste à créer un prototype ou une preuve de concept dans une draft PR qui n’a pas vocation à être fusionnée, à recueillir des retours tôt pour aligner l’approche, puis à conserver cette PR comme trace des idées de conception
- Cette méthode suppose une maturité organisationnelle permettant de jeter sans hésiter la première solution ; la capacité à implémenter un même problème de 2 ou 3 façons est considérée comme un signe de séniorité
- Une PR devient un document repérable qui capture l’intention d’implémentation et les discussions à un moment donné, tandis qu’un document de conception, s’il n’est pas mis à jour fréquemment, risque de devenir une “undead documentation” décalée par rapport à la réalité
- Les documents de conception restent néanmoins utiles pour structurer les retours de multiples parties prenantes, servir de document North Star à long terme, formaliser des idées encore difficiles à coder, ou dans des organisations où un prototype risque d’être déployé tel quel
Explorer la conception avec une Throwaway PR
- Le flux de développement idéal ressemble à ceci : rédiger un document de conception, fusionner successivement de petites PR pour livrer la fonctionnalité, et conserver un historique Git propre
- En pratique, c’est souvent seulement après avoir commencé à coder que les hypothèses du document de conception vacillent, et qu’il faut réévaluer l’ordre de livraison
- Dans ce cas, il peut être plus efficace de commencer par une grosse expérimentation de code, puis d’établir le vrai plan à partir de ses résultats
-
Procédure proposée
- Implémenter un prototype ou une preuve de concept dans une draft PR sans intention de fusion
- Obtenir tôt le regard d’autres personnes sur un gros refactoring ou sur l’approche d’une fonctionnalité afin d’aligner la direction
- Documenter l’approche dans la draft PR afin de conserver une trace historique des idées de conception
- Se préparer à jeter l’intégralité de la draft PR le plus tôt possible
- Extraire progressivement de la draft PR de vraies PR prêtes pour le déploiement, en les découpant sur environ une semaine en PR propres destinées à la mise en production
- À mesure que chaque PR est découpée en étapes, combler progressivement les lacunes en matière de tests et de robustesse
-
Conditions requises côté équipe
- La condition la plus importante est la maturité nécessaire pour pouvoir abandonner sa première idée codée
- Être à l’aise avec l’idée de coder un même problème de 2 ou 3 façons peut être vu comme un signal important de séniorité
- La valeur livrée ne se mesure pas au nombre de lignes de code entrées en production, mais à la connaissance acquise par l’organisation
- Obtenir un alignement précoce sur les points importants évite que le prototypage ne se résume ensuite à du simple gaspillage
- Il faut être suffisamment familier avec la codebase pour relier rapidement ses parties essentielles ; ce niveau d’aisance est attendu d’un profil senior
- Cette méthode peut être pratiquée individuellement comme à l’échelle d’une équipe
La documentation via les PR et le vrai rôle des documents de conception
- Une PR est l’une des formes de documentation les plus utiles pour les développeurs
- C’est souvent l’un des premiers endroits où l’on cherche à comprendre pourquoi une implémentation a été faite ainsi
- Elle ne prétend pas refléter l’état actuel, mais reste comme un artefact historique capturant l’état à un moment donné
- Si un document de conception n’est pas maintenu à jour fréquemment, il risque facilement de devenir une undead documentation reflétant une réalité dépassée
- Un prototype correspond bien au principe du “show, don’t tell”, et lorsqu’il s’agit de provoquer un changement, le code peut être plus efficace que la documentation
- Cela dit, dans une organisation peu disciplinée, un prototype risque d’être perçu non comme une “question”, mais comme une “réponse”
- L’intention initiale est plus proche de « faut-il faire ceci, ou plutôt autre chose ? »
- Le problème apparaît lorsque l’organisation l’interprète comme « il faut faire ceci »
-
Cas où un document de conception reste pertinent
- Il est utile lorsqu’il faut rassembler et conserver les retours de multiples parties prenantes, de managers ou d’équipes externes
- GitHub seul peut ne pas suffire à gérer ce type de collaboration
- Si l’idée est trop conceptuelle et trop long terme pour être codée immédiatement, disposer d’un certain niveau de document North Star peut aider
- Il est aussi utile lorsqu’exprimer l’idée par écrit est plus efficace qu’un premier brouillon de code, ou quand l’onboarding à la codebase n’est pas encore suffisant et qu’on veut laisser une ébauche pour recueillir des retours
- Si l’entreprise pousse directement au déploiement en production de la première solution sans la discipline nécessaire pour l’abandonner, le prototype peut se figer tel quel en “solution”
- Dans une organisation où un junior a du mal à contester l’implémentation des idées d’un développeur senior, il peut être utile de disposer d’un artefact plus souple permettant de poser des questions plus sereinement
-
Quand les documents de conception sont utilisés pour de mauvaises raisons
- Ils peuvent devenir un moyen de ralentir le processus dans des équipes manquant de discipline ou de maîtrise
- Même utilisés à des fins de documentation, ils deviennent généralement vite obsolètes
- Il est difficile de répondre à l’avance à toutes les questions de conception, et les vrais problèmes n’apparaissent souvent qu’une fois le code écrit
- Si l’équipe peut atteindre un niveau suffisant de discipline, apprendre en hackant peut être plus efficace que la “conception”
1 commentaires
Commentaires Hacker News
On appelle ça du prototypage ; c’est une partie précieuse du processus de conception, et certains appellent aussi cela du « pathfinding »
Tout cela constitue des entrées pour la conception, mais une conception de taille appropriée reste nécessaire. Sinon, on se contente de bricoler au fil de l’eau. Il faut définir quel problème on essaie de résoudre et quelle est la solution. Parfois, un document d’une page sans revue formelle suffit ; parfois, il faut un document de plusieurs pages avec plusieurs semaines de revue et d’itérations de feedback
À ne pas oublier : « quelques semaines de code peuvent faire économiser quelques heures de planification » ;)
En fait, c’est bien plus souvent l’inverse qui s’est vérifié. Les gens planifient encore et encore, jusqu’à ce que cette planification dépasse le stade de l’inutilité et nuise activement à la productivité
Quelques semaines de code peuvent faire économiser quelques heures de planification, mais quelques semaines de planification peuvent aussi être gaspillées. Sur le papier, il est facile d’écrire des choses absurdes ou impossibles. Par exemple : « peindre une flotte de licornes d’une couleur à moitié triste »
Idéalement, conception et prototype devraient évoluer ensemble, chaque itération de l’un alimentant l’itération suivante de l’autre, en progression hélicoïdale comme une double hélice d’ADN. Le grand avantage d’un biais vers la création de prototypes, c’est qu’à la fin d’un cycle il reste au moins un logiciel qui fait réellement quelque chose. À la fin d’un cycle de conception, il ne reste en pratique pas grand-chose
Et jusqu’à l’étape d’implémentation, il faut continuer à privilégier le caractère jetable du code. Plus il est facile à supprimer, mieux c’est
Mais l’ingénierie logicielle sans document de conception ni aucune forme de spécification, même très concise, ce n’est pas de l’ingénierie ; c’est plus proche de la construction d’une cabane dans les arbres
Plus le projet gagne en ampleur et en importance, plus les problèmes et la dette technique commencent à apparaître rapidement
Écrire est vraiment utile pour explorer l’espace du problème
Il m’est souvent arrivé de penser que je comprenais bien le problème, puis de commencer à l’écrire et de voir surgir de nouvelles questions importantes. En général, elles se voient mieux à un niveau d’abstraction plus élevé, ou peuvent ne pas apparaître dans les premières étapes de livraison
Cela me rappelle un mentor rencontré au début de ma carrière. C’était quelqu’un qui avait conçu après coup une architecture active/active pour une passerelle de paiement, et qui, en ouvrant Lucidchart, a dit : « ce diagramme représente six mois de ma vie »
Ce n’est pas toujours nécessaire ni utile, mais quand ça l’est, quelques jours de planification peuvent faire économiser plusieurs semaines de code
Il pouvait anticiper bien plus tôt les zones où des problèmes risquaient d’apparaître, si bien que les projets se passaient toujours sans accroc. Quand un problème ou une incertitude apparaissait, il modélisait juste cette partie, puis revenait au tableau blanc pour continuer
Pour prendre une analogie, c’était comme préparer un road trip avec une carte. De nos jours, les documents de conception se contentent d’indiquer la route puis on prend immédiatement le volant, alors que la carte au tableau blanc de ce manager « surplanifiait » tout : où faire le plein, les horaires des attractions touristiques, les papiers pour passer la frontière, le budget global, le kit d’urgence, le plan A et le plan B
C’était terriblement ennuyeux, mais bien meilleur que du code jetable. Maintenant, ne pas surplanifier me donne l’impression d’être paresseux
Bien sûr, le dicton « tout le monde a un plan jusqu’à ce qu’il se prenne un coup » est vrai, mais cela s’applique à la guerre, à la politique et aux négociations, pas au code
Au final, une bonne PR contient aussi beaucoup d’écrit et produit le même effet. Je trouve qu’une PR brouillon bien documentée vaut mieux qu’une proposition de conception pure. Quand on n’écrit que du texte, on oublie des contraintes importantes qui ne viennent à l’esprit que lorsqu’on est dans le code
-- Dick Guindon
Le plus gros problème que j’ai rencontré avec les documents de conception, c’est que personne ne les lit. Même quand l’employeur les exige
Le plus gros problème que j’ai rencontré avec le prototypage, c’est que les gens le considèrent comme du « code de production » et insistent pour l’utiliser comme code final
C’est pourquoi une approche hybride m’a toujours mieux convenu. Je consacre beaucoup de temps à la planification et à la documentation, mais fondamentalement pour moi-même, et j’écris ensuite du code prototype de qualité production qui pourra, plus tard, être réutilisé dans le produit final si besoin
Les documents de conception finissent par devenir un amas de notes brutes que personne, à part leur auteur, ne comprend vraiment, et les gens finissent par redouter la lecture de telles notes
En revanche, si on fait comprendre à l’auteur d’un document de conception qu’il s’agit de quelque chose comme un mémoire de fin d’études noté à l’école, son texte peut devenir très bon après quelques réécritures. Le symptôme est le même qu’avec le prototypage. Les gens rédigent des documents de conception au niveau brouillon, puis s’attendent à ce que, par magie, cela devienne un bon texte adapté à un lectorat plus large. De la même façon qu’un code prototype doit être refactoré plusieurs fois, un document de conception a aussi besoin de plusieurs cycles d’édition.
Pour éviter un renouvellement de contrat, il fallait construire et livrer quelque chose avant la date limite, et ce contrat devait valoir plusieurs millions de dollars. Mais il est devenu clair qu’avec les ressources et l’approche prévues, il serait impossible de terminer à temps
J’ai donc obtenu l’autorisation de fabriquer rapidement une version temporaire, partielle et non optimale, ce qui nous a permis de décoller à temps
Grâce à cela, nous avons pu voler pendant un moment pendant que d’autres terminaient une version permanente et correcte de cette partie de l’aile
En fait, une fois en vol, nous avons aussi découvert des exigences absentes de la conception initiale. Cela a retardé la mise en production de la vraie version, mais j’ai pu les ajouter rapidement à ma version bricolée pour maintenir le vol
Ma version bricolée sert aussi d’outil de support de production. Elle fait également office de solution de repli quand la version permanente a un bug et doit être arrêtée. C’est un bricolage partiel et incomplet, mais il a ses avantages
Certaines personnes se sont plaintes que le langage utilisé était moins courant. Mais il faut se rappeler qu’avec les ressources et l’approche existantes, nous n’aurions de toute façon pas pu décoller au départ
Pour tenir l’échéance, il aurait fallu davantage de développeurs, ou des développeurs plus rapides, dans le langage préféré. Si quelqu’un parmi les employés actuels, moi compris, avait eu la marge et la capacité d’être aussi productif dans le langage préféré que je l’étais avec mon bricolage dans un langage marginal, cette personne aurait été affectée à la solution permanente à temps. Cette option n’existait pas
Quoi qu’il en soit, si un outil de support de production existe déjà, cela fait aussi un endroit où des fonctionnalités prototypes peuvent rester pendant un moment
Encore un billet d’opinion, sans données ni même exemple concret
Tous les ingénieurs logiciels ont des opinions tranchées, je le sais bien, mais ici l’argument est faible. Si vous pensez que votre métier consiste à écrire beaucoup de code pour voir ce qui est juste, vous serez bientôt remplacé par GPT. Il peut le faire plus vite et moins cher. La partie difficile a toujours été d’obtenir un accord sur ce qu’il faut construire, et le code ne permet pas d’échapper à ce problème
Si les exigences sont claires et que ce que je vais livrer l’est aussi pour tout le monde, ce n’est pas nécessaire. On peut passer directement au prototypage. Mais dans les projets sérieux, c’est rare. Il y a toujours des inconnues qu’il faut faire émerger auprès des parties prenantes, et l’analyse technique est une bonne façon d’y parvenir
Les rectangles et les pointillés ont leurs limites. Quand on est éloigné du vrai code, on oublie les contraintes réelles. Ce qui ralentit vraiment n’apparaît pas dans Google Docs. Dans mon expérience, pointer un brouillon de PR en disant « voilà ce que j’ai en tête » mène plus loin
Et oui, c’est une opinion à 100 %. C’est un blog personnel, pas un article évalué par les pairs :) Je peux me tromper, ce n’est pas grave
Sans quelque chose de tangible pour ancrer la conversation, comme du code, les discussions autour d’une conception abstraite finissent facilement en débat sans fin du type « la ficelle dans mon imagination est plus longue que la ficelle dans la tienne »
D’après mon expérience, les retours sur le code et les retours sur la conception sont de nature radicalement différente
Les documents de conception suscitent des questions de type « pourquoi » qui poussent tout le monde à réfléchir à l’espace du problème. Par exemple, des commentaires comme : « Pourquoi proposer un serveur web Rust alors que personne dans l’entreprise n’est encore à l’aise avec Rust ? »
Ce genre de question subtile devient bien plus difficile à soulever une fois qu’un prototype commence à fonctionner. On glisse facilement vers : « Pourquoi l’expérience de l’équipe serait-elle importante ? Regardez comme ça marche bien ! Si personne ne bloque, on peut juste polir le prototype et le mettre en production en une semaine ! »
C’est particulièrement vrai quand on ne relit qu’une conception et pas du code qui fonctionne
Nous imaginons que le travail logiciel suit un flux propre et ordonné
On écrit un document de conception, on produit dans des PR de petits changements incrémentaux pour livrer la fonctionnalité, et l’historique Git reste propre et bien rangé. Cela donne l’impression d’une progression régulière
Qui imagine ça ? Des professeurs qui enseignent le génie logiciel ?
Cela me fait penser aux gens qui croient qu’on écrit de la prose, un essai, une histoire ou un roman en faisant d’abord un plan puis en le « remplissant » ensuite avec du texte. Comme s’il n’y avait aucune découverte au cours du processus qui obligerait à réécrire ou restructurer le document. Personne n’écrit comme ça. Un premier jet est toujours mauvais, et presque tout bon texte est le résultat de grosses révisions
Écrire du code est bien plus proche de l’écriture que de la construction d’une maison ou d’un pont
Le fait de suivre la nouvelle logique ligne par ligne, d’observer les variables et la mémoire, aide vraiment à améliorer le code. On remarque des choses comme : « Ah, cette variable locale ne sert à rien », « Ici je devrais ajouter une variable temporaire pour faciliter le débogage », « Ce code se comporte bizarrement si la collection itérée est vide »
Quel que soit l’âge qu’on a, ou la quantité de code déjà écrite, on découvre toujours quelque chose de nouveau quand on débogue du code qu’on vient d’écrire. On peut comparer ça à un auteur qui relit son brouillon après l’avoir écrit, ou qui se le lit à voix haute, à lui-même ou à quelqu’un d’autre
J’aime beaucoup cette façon de capturer le processus de consignation des décisions de conception comme un fil de commentaires continu, plutôt que d’essayer de les formaliser dans un document unique
C’est comme ça que j’utilise les issues GitHub, mais fonctionnellement c’est pareil qu’utiliser des PR. Une PR est en fait une issue GitHub à laquelle est attachée une branche de code
J’ai écrit davantage sur ma méthode ici : https://simonwillison.net/2022/Jan/12/how-i-build-a-feature/...
Autrement dit, comment résumez-vous ce fil en document final ?
Je ne pense pas que les deux soient mutuellement exclusifs
Un document de conception est un concept plus large, et son objectif est la communication
Il faut parfois transmettre autrement que par le code. Des diagrammes, des images ou du texte sont nécessaires
Il est très difficile, pour quelqu’un qui n’est pas l’auteur ou qui n’est pas très familier avec le code, de comprendre les changements d’un seul coup d’œil. Pour que le lecteur construise rapidement le bon modèle mental afin de comprendre les modifications dans leur contexte, il faut une explication de haut niveau et de la documentation
Si vous pouvez regarder un diff de 1000 lignes et dire précisément ce qu’il fait, et plus important encore quels effets il a en amont et en aval, alors soit vous mentez, soit vous travaillez dans un environnement tellement parfaitement fermé et vérifiable que je vous envie vraiment
Les documents de conception aident à ramener à 2 ou 3 le nombre de prototypes parmi les options possibles. Ils sont particulièrement utiles quand on explore l’ajout de quelque chose de totalement nouveau
J’ai l’impression que montrer vaut mieux qu’expliquer, mais les nouveaux arrivants comprennent plus facilement via un document de conception qu’à travers le code