Dans le chapitre précédent, nous avons vu quelques bonnes pratiques et des exemples concrets pour représenter votre architecture.
Dans ce chapitre, nous allons voir quelques outils standard pour documenter votre projet et son architecture, afin de rendre votre documentation formelle et professionnelle.
Décrivez votre système en fonctionnement
Commençons par un exemple :
Vous et votre équipe allez développer une nouvelle application logicielle pour la Direction de l'immigration dans votre pays. Un sérieux problème se pose dans la zone réservée à l'immigration dans le principal aéroport du pays : lorsque les voyageurs présentent leur passeport à l'arrivée, si celui-ci provient d'un certain groupe de pays, le douanier doit changer d'écran et effectuer une recherche dans un autre système pour y récupérer certaines données spécifiques. Cela retarde considérablement la procédure d'entrée dans le pays, et se traduit par de longues files d'attente dont les usagers se plaignent, et expriment généralement leur mécontentement en dénonçant « l'inefficacité » du service.
Vous et votre équipe allez développer la version 2 du système, qui consistera en une mise à niveau qui fonctionnera dans tous les aéroports du pays. Elle devra résoudre ce problème et ajouter des fonctionnalités supplémentaires.
Vous allez rédiger la documentation du nouveau système. Celle-ci sera utilisée par les développeurs, les administrateurs de bases de données, les concepteurs d'expérience utilisateur et les responsables du produit.
Êtes-vous censé y faire apparaître le problème précédent, que nous venons de décrire ?
Absolument ! Vous devez inclure le problème actuel, ainsi que la façon dont la version 2 devrait le résoudre.
Mettez votre équipe en prise avec le monde extérieur, expliquez-lui les problèmes que vous allez résoudre lorsque le système sera opérationnel.
Utilisez des schémas pour représenter les systèmes
Utilisez une convention, le langage UML
UML permet de visualiser les composants architecturaux d'un système, notamment des éléments tels que les suivants :
activités du système ;
composants individuels du système et façon dont ils interagissent avec d'autres composants logiciels ;
façon dont le système fonctionnera ;
façon dont les entités interagissent avec d'autres (composants et interfaces) ;
interfaces utilisateur externes.
Voici comment on représente une classe en UML :
Voici une classe appelée Compte bancaire.
Cette classe comporte deux attributs : le propriétaire du compte, de type « chaîne », et le solde du compte, un champ numérique exprimé en dollars des États-Unis.
La classe comporte deux méthodes : dépôt d'un montant sur le compte et retrait d'un montant.
Voici comment une interaction entre composants est représentée en UML :
Voici un schéma pour un restaurant. Il comporte deux acteurs : le critique gastronomique et le chef. Les ellipses à l'intérieur du rectangle représentent les processus exécutés dans le restaurant.
Pouvez-vous décrire le système logiciel que vous et votre équipe allez développer à l'aide de ce type de composants visuels ? Cette description prend du temps, mais une fois achevée, elle permettra à toutes les personnes impliquées de comprendre très clairement votre système. Lorsque vous expliquez votre système de façon visuelle, vous parvenez à mieux le comprendre… Cela vaut donc la peine d'essayer !
Utilisez votre créativité pour des schémas plus personnalisés
Je voudrais vous montrer une deuxième façon de documenter un système, plus naturelle, plus facile, mais qui nécessite davantage de créativité.
Si vous souhaitez esquisser rapidement vos idées, vous pouvez bien sûr utiliser un crayon et du papier...
Mais, une fois votre dessin terminé, vous devez en faire une version numérique plus propre pour pouvoir la communiquer à vos collègues. Cela pourra donner ceci :
Utilisez les User Stories pour décrire les fonctionnalités
Les User Stories sont souvent rédigées du point de vue de l'utilisateur final d'un système, et sont largement utilisés dans le cadre de projets agiles. Elles sont souvent notées sur des fiches bristol, des post-it ou des logiciels de gestion de projet, et présentent la syntaxe suivante :
En tant que (RÔLE), je veux (ACTION) afin de (OBJECTIF).
Par exemple :
En tant que client, je veux voir la liste de mes précédentes commandes sur le site web et afficher le détail de chacune d'entre elles, afin de visualiser mon historique de commandes.
Nous pouvons ainsi dire que la fonctionnalité d'un système est une série de « fiches » comme celle-ci, qui sont remises aux développeurs. Dans les projets agiles, les User Stories sont très souvent présentées et gérées dans des storyboards.
Prenons ce schéma simple d'un système d'envoi de messages :
Nous avons un utilisateur et un e-mail. Le message est stocké dans un serveur de messagerie. Ce serveur envoie et reçoit des messages en provenance de smartphones, de tablettes, de PC et d'ordinateurs portables.
Comment décrire cette situation à l'aide d'une User Story ?
Comme ceci :
En tant qu'utilisateur du système, je veux écrire un message à un contact et l'envoyer afin de lui permettre de le lire immédiatement sur n'importe quel appareil.
Les User Stories sont en général écrites sur des fiches ou des post-it, mais peuvent se faire sur des outils digitaux comme Miro :
Dans un projet agile, un ensemble de User Stories d'utilisateurs s'appelle un Product Backlog (ou carnet du produit). Chaque User Story est attribuée à un membre de l'équipe, ici Alex.
Expliquez la fréquence et le type des flux de données
Un autre élément à prendre en compte est la fréquence de ces interactions entre composants : Quand le processus commence-t-il ? Comment se termine-t-il ? Que se passe-t-il au milieu ?
Voici la séquence d'événements qui crée un flux de données avec des données réelles :
Quand le processus commence-t-il ? Un client navigue sur un site WebStreet et affiche une liste d'articles. Il est intéressé par l'un des articles de la liste et clique dessus.
Que se passe-t-il au milieu ?
Le client clique sur le bouton Quitter.
Le client clique sur l'un des articles de la liste. Dans ce cas, l'écran de passage en caisse s'affiche, et l'article est acheté.
Comment se termine-t-il ? Le flux de données peut s'achever de deux façons :
Le client a cliqué sur le bouton Quitter.
Le client a acheté un article.
Dans ce cas, nous dirons que l'utilisateur déclenche le processus : ce processus est initié par l'utilisateur lorsqu'il clique sur l'article qu'il souhaite acheter. Ce processus est asynchrone. Inversement, il existe des processus synchrones, par exemple des processus par lots qui s'exécutent tous les soirs à la même heure.
Ça y est, ce cours touche à sa fin ! J'espère que vous avez pu y découvrir de nombreux bons conseils pour faire votre propre code autodocumenté et documenté, afin de le communiquer à vos collaborateurs. Rendez-vous au dernier quiz de ce cours pour tester vos connaissances.
En résumé
Utilisez des schémas : un schéma est une représentation symbolique d'informations, à l'aide de techniques de visualisation.
Utilisez l'Unified Modeling Language (UML, langage unifié de modélisation) : un langage généraliste de modélisation du développement, qui permet de visualiser la conception d'un système de façon standardisée.
Utilisez des schémas dessinés à la main.
Utilisez des User Stories pour décrire les fonctionnalités d'un système : le comportement entre des entrées et des sorties à travers une interface utilisateur :
"En tant que (RÔLE), je veux (ACTION) afin de (OBJECTIF)."Expliquez comment les interactions et les données figurant sur les schémas évoluent avec le temps.
Indiquez dans votre documentation si votre processus est synchrone ou asynchrone. Documentez les déclencheurs.
