Je suis un développeur amateur et tous mes programmes jusqu'à présent étaient assez simples pour être documentés dans le code. En lisant le code, il était clair ce que je faisais telle ou telle action (mon test standard consistait à regarder le code 6 mois plus tard et à tout comprendre à la première lecture - et ma mémoire est courte).
Je suis maintenant confronté à un programme qui dépasse mes capacités à se souvenir des diverses interactions entre
- le code lui-même
- les index de la base de données
- les interactions entre les différents modules (code de base "travailleur" et "bibliothèque")
Ma documentation actuelle est un tableau blanc où j'ai toutes sortes de boîtes et de flèches qui pointent vers du code, vers des index de base de données, vers des actions en cours d'exécution, pour changer d'état, etc. Juste pour référence, un fragment du gâchis:
Ma question est de savoir s'il existe un ensemble standard ou nommé de meilleures pratiques (nommé en ce sens qu'il s'agit d'un ensemble de pratiques regroupées sous un nom spécifique) pour la documentation de produits plus complexes.
Quels sont les mots-clés que je devrais rechercher (les tentatives générales de «documenter les normes d'architecture logicielle» et les variations similaires conduisaient généralement à des logiciels pour les workflows ou la construction de systèmes CAO d'architecture).
Je m'attends également à ce qu'il n'y ait pas de meilleures pratiques générales pour les descriptions de haut niveau et que chacun construise sa propre philosophie.
Réponses:
Il n'y a pas une norme à laquelle tout le monde adhère. Les projets logiciels peuvent varier considérablement (pensez: helloworld.py vs le code de la navette spatiale).
Une méthode très courante consiste à utiliser le modèle 4 + 1 . Au lieu d'essayer de tout regrouper en un seul style de document, cette méthodologie décompose la conception en cinq composants:
Les différentes vues décrivent le produit selon quatre perspectives différentes. Les scénarios indiquent où vivent les cas d'utilisation et décrivent l'interaction des autres vues.
Remarque: Il s'agit d'un modèle conceptuel et n'est lié à aucun outil spécifique.
Vous pouvez lire plus ici:
la source
IMHO UML n'est pas un outil qui fonctionne bien pour documenter l'architecture des logiciels du monde réel. Les diagrammes de classes sont utiles, mais utilisent un niveau d'abstraction qui est souvent trop faible à cet effet. Les diagrammes de cas d'utilisation sont généralement trop «de haut niveau» et manquent certains aspects. D'autres types de diagrammes UML ont des problèmes similaires (pour être honnête, les diagrammes de packages, les diagrammes de déploiement, les diagrammes de composants peuvent documenter certains aspects architecturaux, mais personnellement, je ne les ai jamais trouvés très utiles).
Si vous cherchez un moyen pratique et pragmatique de documenter des architectures de haut niveau, je vous suggère de vous familiariser avec les diagrammes de flux de données . Celles-ci sont faciles à comprendre et ont l'avantage de pouvoir s'adapter à différents niveaux d'abstractions. Je les ai trouvés très utiles pour documenter différents types de systèmes. Dommage qu'ils n'aient pas trouvé leur chemin dans UML, mais vous trouverez néanmoins de nombreux outils - même gratuits comme Dia ou DrawIO - pour créer ces diagrammes.
En guise de remarque, pourquoi avez-vous besoin des "index dans la base de données" dans une documentation de haut niveau? Je pense qu'ils sont un détail d'implémentation de votre modèle de données (relationnel?), Et si vous les ajoutez ou non est - selon mon expérience - plus une question de performances et d'optimisation.
la source
Le langage de modélisation unifié (UML) est un langage de modélisation de développement à usage général dans le domaine du génie logiciel, qui est destiné à fournir un moyen standard de visualiser la conception d'un système.
la source
Je pense que nous faisions mieux. UML semblait jeter le bébé avec de l'eau du bain. En fournissant un langage de modélisation unifié, il a supprimé la distinction entre architecture et implémentation. Ou si elle n'avait pas l'intention de le faire, cela semblait être le cas.
J'ai vu des modèles UML monstres et franchement, ils ne font rien pour moi que le code ne puisse pas faire, et le font mieux.
la source