Infos sur l’ingénierie
Une compétence importante pour tout ingénieur logiciel est la rédaction de documents de conception technique (TDD), également appelés documents de conception technique (EDD). Ici, dans cet article, je propose quelques conseils pour écrire de bons docs de conception et quelles sont les erreurs à éviter.
Une mise en garde : différentes équipes auront différentes normes et conventions pour la conception technique. Il n’y a pas de norme industrielle pour le processus de conception, et il ne pourrait pas y en avoir, car différentes équipes de développement auront des besoins différents en fonction de leur situation. Ce que je vais décrire est une réponse possible, basée sur ma propre expérience.
Commençons par les bases : Qu’est-ce qu’un doc de conception technique, et comment s’inscrit-il dans le processus de conception ?
Un doc de conception technique décrit une solution à un problème technique donné. Il s’agit d’une spécification, ou d’un « plan de conception », pour un programme ou une fonctionnalité logicielle.
La fonction première d’un DDT est de communiquer les détails techniques du travail à effectuer aux membres de l’équipe. Cependant, il existe un second objectif qui est tout aussi important : le processus de rédaction du TDD vous oblige à organiser vos pensées et à considérer chaque aspect de la conception, en vous assurant que vous n’avez rien oublié.
Les docs de conception technique font souvent partie d’un processus plus large qui comporte généralement les étapes suivantes :
- Les exigences du produit sont définies. Celles-ci seront généralement représentées par un document d’exigences du produit (PRD). Le PRD spécifie ce que le système doit faire, du point de vue d’un utilisateur ou d’un agent extérieur.
- Les exigences techniques sont définies. Les exigences du produit sont traduites en exigences techniques – ce que le système doit accomplir, mais maintenant comment il le fait. Le résultat de cette étape est un document d’exigences techniques (TRD).
- Conception technique. Elle contient une description technique de la solution aux exigences décrites dans les étapes précédentes. Le TDD est le résultat de cette étape.
- Mise en œuvre. C’est l’étape où la solution est effectivement construite.
- Test. Le système est testé par rapport au PRD et au TRD pour s’assurer qu’il répond effectivement aux exigences spécifiées.
Entre chacune de ces étapes, il y a généralement un processus de révision pour s’assurer qu’aucune erreur n’a été commise. Si des erreurs, des malentendus ou des ambiguïtés sont détectés, ils doivent être corrigés avant de passer à l’étape suivante.
Ce processus est très variable ; l’ensemble des étapes énumérées ici changera au cas par cas. Par exemple :
- Pour les petites fonctionnalités qui n’impliquent pas beaucoup de complexité, les étapes 2 et 3 seront souvent combinées en un seul document.
- Si la fonctionnalité implique un grand nombre d’inconnues ou un certain niveau de recherche, il peut être nécessaire de construire une implémentation de preuve de concept avant de finaliser la conception technique.
Ce processus se produit également à différentes échelles et niveaux de granularité. Un PRD / TRD / TDD peut concerner la conception d’un système entier, ou d’une seule fonctionnalité. Dans la plupart des environnements, le processus est également cyclique – chaque cycle de conception/mise en œuvre s’appuie sur le travail du précédent.
La ligne de démarcation entre TRD et TDD peut parfois être un peu floue. Par exemple, supposons que vous développez un serveur qui communique via une API RESTful. Si l’objectif est de se conformer à une API déjà établie et documentée, alors la spécification de l’API fait partie des exigences et doit être référencée dans la DRT. Si, au contraire, l’objectif est de développer une toute nouvelle API, la spécification de l’API fait partie de la conception et doit être décrite dans le TDD. (Cependant, le document d’exigences doit toujours spécifier ce que l’API essaie d’accomplir.)
Écrire le TDD
De nos jours, il est courant de rédiger des docs techniques dans un système de document collaboratif, tel que Google Docs ou Confluence ; cependant, ce n’est pas une exigence absolue. L’important est qu’il y ait un moyen pour les membres de votre équipe de pouvoir faire des commentaires sur le document et de signaler les erreurs et les omissions.
La plupart des TDD font entre une et dix pages. Bien qu’il n’y ait pas de limite supérieure à la longueur d’un TDD, les documents très volumineux seront à la fois difficiles à éditer et difficiles à absorber pour les lecteurs ; envisagez de le diviser en documents distincts représentant les différentes étapes ou phases de la mise en œuvre.
Les diagrammes sont utiles ; il existe un certain nombre d’outils en ligne que vous pouvez utiliser pour intégrer des illustrations dans le document, comme draw.io ou Lucidchart. Vous pouvez également utiliser des outils hors ligne tels que Inkscape pour générer des diagrammes SVG.
Le document doit être complet ; idéalement, il doit être possible pour quelqu’un d’autre que l’auteur du TDD de mettre en œuvre la conception telle qu’elle est écrite. Par exemple, si la conception spécifie une implémentation d’une API, chaque point de terminaison de l’API doit être documenté. S’il y a des choix de conception subtils, ils devraient être appelés.
Éviter les erreurs d’écriture communes
Probablement l’erreur la plus courante que je rencontre dans les TDD est un manque de contexte. C’est-à-dire que l’auteur a écrit, en aussi peu de mots qu’il a pu gérer, comment il a résolu le problème ; mais il n’a pas inclus d’informations sur ce qu’était le problème, pourquoi il devait être résolu, ou quelles étaient les conséquences du choix de cette solution particulière.
De plus, il est important de garder à l’esprit qui est le lecteur probable, et quel est son niveau de compréhension. Si vous utilisez un terme que le lecteur pourrait ne pas connaître, n’ayez pas peur d’en ajouter une définition.
Il est à peine nécessaire de préciser qu’une bonne grammaire et une bonne orthographe sont utiles. Aussi, évitez la tentation du jeu de mots ou de l’orthographe « mignonne » ; alors que les programmeurs en tant que classe ont tendance à aimer jouer avec le langage, j’ai vu plus d’un cas où une frivolité excessive a fini par coûter à l’équipe des efforts perdus à cause de malentendus. Il n’y a pas de mal à faire de l’humour de temps en temps ou à choisir des noms colorés et mémorisables pour les fonctionnalités et les systèmes, car cela aide les gens à s’en souvenir. Mais ne laissez pas votre désir de montrer à quel point vous êtes intelligent devenir une distraction.
En parlant de noms, choisissez-les avec soin ; comme Mark Twain l’a écrit un jour, » Choisissez le bon mot, pas son cousin au second degré « . Les ingénieurs au vocabulaire pauvre ont tendance à utiliser les mêmes termes génériques à plusieurs reprises pour des choses différentes, ce qui entraîne une surcharge et une confusion. Par exemple, nommer une classe « DataManager » est vague et ne vous dit rien sur ce qu’elle fait réellement ; de même, un paquet ou un répertoire nommé « utils » peut contenir pratiquement n’importe quoi. Consultez un thésaurus si vous avez besoin de trouver un meilleur mot, ou mieux, une base de données de synonymes spécialisée telle que WordNet.
TDD Template
Lorsque vous écrivez une TDD, il peut être utile de commencer avec un modèle standard. Ce qui suit est un modèle que j’ai utilisé dans un certain nombre de projets. Notez que ce modèle doit être personnalisé au besoin ; vous êtes libre de supprimer les sections qui ne s’appliquent pas, d’ajouter des sections supplémentaires ou de renommer les titres, le cas échéant.