Je ne pense pas que ce que dise Uncle Bob est ridicule, vu les ouvrages de référence qu'il a écrit (Clean Code, principe SOLID, etc.).
Tout n'est pas ridicule, mais il me semble en effet ridicule de croire que le code source contient toutes les informations utiles pour un projet d'envergure.
Comme toute analogie, elle a ses limites, mais elle me parait légitimer le code en tant que document de référence qu'il faut garder le plus lisible possible.
Sauf que, comme je l'ai dit, le code ne peut servir de référence ultime :
Nombreux sont ceux qui ne savent pas le lire, et les docs générés à partir des sources sont compris par des codeurs, rarement par des non-codeurs ;
Un projet a un contexte, des contraintes, rarement exprimés dans le code (car ce n'est pas le rôle du code que de décrire le projet de A à Z) donc il sera nécessaire de détailler tout cela dans des documents annexes au code ;
Dans un projet non uniquement informaticien-centré, tu as des tas de métiers qui vont intervenir, dialoguer entre eux, etc. Je pense à des gens du matériel, des ergonomes, des architectes logiciels (qui n'ont pas codé dans le langage X depuis un bail), des auditeurs qualité, des testeurs, des ingénieurs systèmes, ou tout simplement le client (qui n'est pas codeur mais celui qui va utiliser le produit).
Le dernier point est souvent oublié mais il est capitale. J'ai bossé avec des non-codeurs et pour eux il est inconcevable qu'ils lisent du code ou qu'ils essayent de trouver l'info qui leur faut dans la documentation du projet qui est dans le code. Ils perdraient trop de temps.
Par exemple, perso je m'occupe souvent de l'interface noyau / matériel et noyau / logiciels. Je ne pouvais pas exiger des ingénieurs électroniciens de lire ma doc pour savoir ce que je fais avec leur matériel. Ils s'en foutent de l'architecture du noyau et des détails dont seul le logiciel a a s'en préoccuper. De même que moi je m'en fou de savoir exactement les plans de routage de la carte électronique dessous.
Résultat, nous devons concevoir une documentation pour décrire l'interface logiciel / matériel, quelle puce est accessible sur quel bus, les registres importants à changer, certaines possibilités en options, les changements exactes entre la version A du matériel et la version B, etc.
Non seulement c'est utile pour nous, éviter de perdre du temps à récupérer les infos pertinentes, cela nous permet d'éviter les erreurs car on doit dialoguer pour se mettre d'accord sur les tâches à faire. En plus comme le projet était en contexte aéronautique, nous devons fournir ce genre de document pour être audité par des non informaticiens (les ingénieurs systèmes).
Et avec les non programmeurs ? Bah c'est aussi utile. Pour beaucoup de programmeurs, le noyau est une boîte noire et doit le rester. Ils s'en foutent de l'architecture de mes pilotes, et en plus la plupart ne savent pas forcément coder en C. Comme pour le matériel, ce qui faut, c'est la description des entrées / sorties. Le reste tout le monde s'en fiche (sauf moi pour maintenir mon propre code). De même que je n'ai pas envie de plonger dans un code écrit dans un langage que je comprends mal pour vérifier si le format des entrées / sorties correspond. Et comme la doc en général ressort toute l'architecture, te peux prendre du temps pour identifier la section qui t'intéresse.
Tout cela pour dire quoi ? Que je trouve très important que l'on documente nos codes à différents échelons. Il faut décrire les interfaces d'entrées / sorties pour ceux qui vont dialoguer avec toi, il faut décrire l'architecture détaillée (dans le code) pour ceux qui vont coder ou reprendre ce module, et il faut décrire une architecture simpliste pour ceux qui vont gérer le projet et faire l'architecture / relecture globale. Cela demande différents niveaux d'abstractions, de formats de documents donc (fichier texte, UML et code). Croire que seul le code avec la doc généré suffit est je pense trop simpliste et ne peut fonctionner pour un projet d'envergure qui fait intervenir des non codeurs dans la procédure.
[^] # Re: la spec, c'est le code
Posté par Renault (site web personnel) . En réponse à la dépêche Développement très rapide d’applications libres : Extended Man/XML Frames. Évalué à 8.
Tout n'est pas ridicule, mais il me semble en effet ridicule de croire que le code source contient toutes les informations utiles pour un projet d'envergure.
Sauf que, comme je l'ai dit, le code ne peut servir de référence ultime :
Le dernier point est souvent oublié mais il est capitale. J'ai bossé avec des non-codeurs et pour eux il est inconcevable qu'ils lisent du code ou qu'ils essayent de trouver l'info qui leur faut dans la documentation du projet qui est dans le code. Ils perdraient trop de temps.
Par exemple, perso je m'occupe souvent de l'interface noyau / matériel et noyau / logiciels. Je ne pouvais pas exiger des ingénieurs électroniciens de lire ma doc pour savoir ce que je fais avec leur matériel. Ils s'en foutent de l'architecture du noyau et des détails dont seul le logiciel a a s'en préoccuper. De même que moi je m'en fou de savoir exactement les plans de routage de la carte électronique dessous.
Résultat, nous devons concevoir une documentation pour décrire l'interface logiciel / matériel, quelle puce est accessible sur quel bus, les registres importants à changer, certaines possibilités en options, les changements exactes entre la version A du matériel et la version B, etc.
Non seulement c'est utile pour nous, éviter de perdre du temps à récupérer les infos pertinentes, cela nous permet d'éviter les erreurs car on doit dialoguer pour se mettre d'accord sur les tâches à faire. En plus comme le projet était en contexte aéronautique, nous devons fournir ce genre de document pour être audité par des non informaticiens (les ingénieurs systèmes).
Et avec les non programmeurs ? Bah c'est aussi utile. Pour beaucoup de programmeurs, le noyau est une boîte noire et doit le rester. Ils s'en foutent de l'architecture de mes pilotes, et en plus la plupart ne savent pas forcément coder en C. Comme pour le matériel, ce qui faut, c'est la description des entrées / sorties. Le reste tout le monde s'en fiche (sauf moi pour maintenir mon propre code). De même que je n'ai pas envie de plonger dans un code écrit dans un langage que je comprends mal pour vérifier si le format des entrées / sorties correspond. Et comme la doc en général ressort toute l'architecture, te peux prendre du temps pour identifier la section qui t'intéresse.
Tout cela pour dire quoi ? Que je trouve très important que l'on documente nos codes à différents échelons. Il faut décrire les interfaces d'entrées / sorties pour ceux qui vont dialoguer avec toi, il faut décrire l'architecture détaillée (dans le code) pour ceux qui vont coder ou reprendre ce module, et il faut décrire une architecture simpliste pour ceux qui vont gérer le projet et faire l'architecture / relecture globale. Cela demande différents niveaux d'abstractions, de formats de documents donc (fichier texte, UML et code). Croire que seul le code avec la doc généré suffit est je pense trop simpliste et ne peut fonctionner pour un projet d'envergure qui fait intervenir des non codeurs dans la procédure.