Que savez-vous du développement basé sur les documents ?

Pourquoi avons-nous même besoin de documents dans le processus de développement ?

Qu'en est-il de cette déclaration que le code documente lui-même ?

Considérons le scénario le plus courant : le code du système (qu'il s'agisse d'un programme, d'un projet ou d'un produit) est écrit sur une longue période, et l'équipe change progressivement au cours de ce processus, emportant avec elle certaines connaissances sur le système au fur et à mesure que les développeurs partent.

Que pouvons-nous faire dans un tel cas ?

La réponse la plus simple consiste à rédiger une spécification qui capture tous les détails de mise en œuvre pour garantir que le système répond aux exigences initiales.

Cependant, un tel document est très difficile à rédiger à l'avance, et au cours du processus de développement, certains détails de mise en œuvre peuvent changer (adaptation au marché/nouvelles demandes de mécanique, etc.). Alors, que pouvons-nous imaginer pour améliorer le facteur bus ?

Essayons de suivre un flux qui pourrait être l'une des solutions possibles pour résoudre le problème mentionné ci-dessus.

Exigences et RFC

Tout d’abord, nous devons décrire la conception initiale en fonction des exigences des parties prenantes et la documenter. Après cela, ce document peut être partagé avec d'autres équipes et leurs commentaires demandés : demander d'implémenter certaines fonctionnalités, commenter la conception initiale, corriger une certaine interface, etc. Un tel document peut être appelé RFC .

RFC , ou « Request for Comments », est un document distribué aux parties intéressées (y compris les développeurs, les architectes et d'autres équipes) pour recueillir des commentaires, des commentaires et des suggestions. Il est moins détaillé qu’une spécification et comprend uniquement le domaine initial du problème, de la tâche et de la solution. Étant plus flexible, il permet d’accepter activement les changements dans la conception, garantissant une compréhension approfondie de la tâche et facilitant une prise de décision réfléchie et de qualité.

Engagement de conception et ADR

D'accord, nous avons défini les exigences techniques et rassemblé les exigences des autres équipes . Et après?

À ce stade, il est nécessaire de finaliser la conception du système et toutes les principales fonctions qu'il remplira. A cet effet, nous rédigeons un ADR .

ADR , ou « Architecture Decision Record », est un document qui enregistre les décisions architecturales importantes prises au cours du processus de développement logiciel. Chaque ADR décrit une décision architecturale spécifique de haut niveau, son contexte, les alternatives envisagées, la décision prise et la motivation pour choisir ces détails spécifiques plutôt que d'autres.

Un tel document permet à chaque membre de l'équipe (et aux autres équipes également) de comprendre les principes et les valeurs qui sous-tendent la conception. Si un nouveau développeur rejoint l'équipe des années plus tard et demande : « Pourquoi avez-vous procédé de cette façon ? », il pourra lui montrer ce document, qui répondra à toutes ses questions.

spécification

Il est maintenant temps d'écrire le code et ses spécifications. À ce stade, nous travaillons minutieusement sur chaque fonctionnalité, en compilant simultanément toutes les informations et détails de mise en œuvre dans un document spécial. Ce document doit refléter les exigences actuelles de bas niveau pour le système.

Un point important : au cours du cycle de vie du logiciel, une telle spécification peut changer considérablement, et ce n'est pas grave. Cependant, il est très important de rester dans la conception et l'architecture d'origine pour éviter que la base de code ne devienne quelque chose d'ingérable.

Plan de test

Pourquoi est-ce nécessaire ? Il est essentiel qu'un plan de test soit construit non pas sur la base d'un code écrit conformément à la spécification (nous écrivons du code et des tests pour ce code afin qu'il réussisse), mais sur la base d'une conception qui inclut des scénarios critiques qui doit être traité correctement . Il est également très pratique que vous puissiez soumettre un tel plan de test pour examen à d'autres équipes (pour des intégrations ou simplement pour des tests supplémentaires), en indiquant clairement comment le système se comportera dans différentes situations.

Que comprend-il ?

• Tous les scénarios possibles de fonctionnement du système

  • Chemin heureux
  • Triste chemin
  • La gestion des erreurs

• Tous les invariants possibles qui doivent être maintenus pendant le fonctionnement du système

• Tests d'acceptation pour vérifier l'état du système au départ (doivent tenir compte de l'environnement, par exemple les données sur le réseau)

  
  

Nous avons finalisé la conception , écrit le code et les spécifications , et compilé le plan de test . Cela semble déjà assez solide ! Mais que pourrions-nous ajouter d’autre ?

Plan de déploiement

Un tel plan pourrait être nécessaire dans une certaine mesure pour améliorer le facteur bus et créer des conditions dans lesquelles n'importe quel membre de l'équipe peut déployer le système et vérifier son état.

Pourquoi ne peut-on pas s'en passer ? Nous pouvons le faire, mais dans le monde réel, il s'agit de grandes équipes où de nombreuses personnes sont responsables de différentes parties du système, et le processus de déploiement peut être entièrement délégué à DevOps. Quel est le problème, puisque nous avons écrit des tests, les avons mis dans CI et vérifié les vulnérabilités, avons-nous besoin d'autre chose ? Peut-être pas, mais souvent les tests ne prennent pas en compte l'état actuel du système et ne testent pas exactement ce que nous souhaiterions.

Quel plan de déploiement peut contenir :

• Une description complète des actions à effectuer pour que le déploiement ait lieu
• Paramètres de déploiement :
  • Variables d'environnement
  • Etat initial
  • Paramètres de lancement
• Un plan en cas de problème à n'importe quelle étape
• Un plan de secours, si possible
• L'état nécessaire dans lequel le système doit être amené au cas où la poursuite du déploiement n'est pas possible
• Actions à effectuer après le déploiement
  • Informer les autres équipes
  • Activer les intégrations nécessaires, si nécessaire

Rien de compliqué, non ? Disposer d'un tel document pour une mise à jour spécifique peut améliorer considérablement le facteur bus et éviter de dépendre de personnes spécifiques. N'est-ce pas ce que nous voulons ?

Conclusion

Dans le processus de développement logiciel, il est important non seulement d'écrire du code, mais également de créer une documentation garantissant la compréhension et la cohérence à toutes les étapes du développement. La documentation peut être le code lui-même , mais l'expérience a montré que la documentation est très importante pour maintenir la qualité, la stabilité et l'évolutivité future du système, en particulier lorsque l'équipe change au cours du développement, et également lorsque le projet évolue et s'adapte aux nouvelles exigences.

La documentation comprend les RFC (Request for Comments), ADR (Architecture Records), les spécifications , les plans de test , les plans de déploiement , etc. Cela garantira la rétention des connaissances dans l'équipe , simplifiera le processus d' intégration des nouveaux employés dans le projet et augmentera la fiabilité globale et la résistance du système aux changements .