Contexte: Mes collaborateurs et moi écrivons un article pour une revue universitaire. Au cours de nos recherches, nous avons écrit un programme de simulation en Java. Nous voulons rendre le programme de simulation disponible gratuitement pour que d'autres puissent l'utiliser. Nous avons décidé d'héberger le code sur un référentiel GitHub. Afin de le rendre facile à utiliser pour les autres, nous voulons écrire une bonne documentation pour notre programme, y compris:

• Javadocs pour chaque classe et méthode
• Comment utiliser le code
• Décrire la structure de haut niveau du code

Ma question de haut niveau est: pourriez-vous fournir un bon exemple des mots et des diagrammes qui peuvent être utilisés pour décrire la structure de haut niveau d'un programme? Cela comprend comme sous-questions:

1. Comment montrer quelles classes sont contenues dans quels packages?
2. Comment montrer quels packages dépendent d'autres packages?
3. Comment montrons-nous comment les objets / classes du programme fonctionnent ensemble?
4. Nous avons essayé d'utiliser des principes de conception pilotés par domaine dans la conception de mon code. Comment montrer la correspondance entre les objets du domaine et les fichiers de code source particuliers codant ces objets? (Voir ma description «langage omniprésent» du projet ci-dessous.)

Ce que j'ai fait jusqu'à présent

Langage omniprésent

Nous mettons une description "du langage omniprésent" du code dans un fichier ubiquitous-language.md, contenu ci-dessous.

Le but de ce projet est d'étudier la performance d'une politique de réapprovisionnement dans une chaîne d'approvisionnement simple avec une seule installation, sous différents modèles de délais, rapports de retards et modèles de demande.

Dans chaque période, les événements suivants se produisent:

1. Si un envoi doit arriver à l' installation à la période en cours, le niveau de stock de l'installation est incrémenté de X unités.
2. Si le calendrier indique que la période en cours est une période de déclaration, l' établissement soumet un rapport au fournisseur . Le fournisseur peut recevoir le rapport instantanément, ou avec un retard de plusieurs semaines, comme spécifié par le calendrier .
3. Si le fournisseur a reçu un rapport , puis sur la base de la politique de réapprovisionnement , il calculera une quantité de réapprovisionnement de X unités. Un envoi de X unités du produit sera programmé pour arriver après un délai de l périodes.
4. Les clients arrivent à l' établissement et à la demande des unités X du produit. Toute demande non satisfaite est perdue.

Structure du code source

Nous mettons une description incomplète "de haut niveau" du code dans un fichier structure.md, contenu ci-dessous.

Structure au niveau du package

Au plus haut niveau, le code source est organisé en trois packages

• com.gly.sfs La classe principale avec la mainméthode réside dans ce package.
• com.gly.sfs.model Les classes de modèle de domaine résident dans ce package.
• com.gly.sfs.util Les classes d'assistance résident dans ce package.

Normalement , vous utiliseriez UML dans le but que vous décrivez. UML se décompose essentiellement en deux types de diagrammes: structurel et comportemental.

Les diagrammes structurels incluent: composition, déploiement, package, classe, objet et composant. Les diagrammes de comportement incluent: séquence, machine d'état, communication, cas d'utilisation, activité et aperçu des interactions.

Selon ce que vous essayez de transmettre, vous choisissez quelques-uns de ces diagrammes qui représentent le mieux ce que vous essayez de transmettre et, ce faisant, vous permettez à la conversation de "monter d'un niveau". Au lieu de parler de méthodes, de paramètres et de code, vous parlez de séquence d'interactions, de dépendances de classes statiques ou de tout diagramme que vous choisissez de créer.

J'ai joint un exemple de diagramme de séquence (l'un des diagrammes de comportement). Personnellement, j'aime le diagramme de séquence, car il est en plein milieu du processus de conception d'artefact - à peu près un nombre égal de diagrammes en dépend comme il l'attend en entrée. Je trouve que les diagrammes d'entrée sont généralement "compris" de toute façon, ou le diagramme de séquence implique déjà leur existence. Cependant, parfois je fais des diagrammes de classes statiques et des diagrammes de séquence (un diagramme structurel et un diagramme comportemental).

http://omarfrancisco.com/wp-content/uploads/2011/07/sequencediagram.png

Je n'ai jamais vu ce diagramme auparavant dans ma vie, mais je peux dire un certain nombre de choses sur ce système. Il existe quatre composants principaux (les noms de votre système - généralement les classes): View, Controller, Data Proxy et Data Provider. Les flèches sont des "comportements" ou des invocations de méthode. Un diagramme de séquence est fondamentalement bon pour montrer une seule interaction importante entre un tas de composants. Vous disposez d'un diagramme de séquence pour chaque flux important dans votre système. Je peux dire à partir de ce diagramme particulier que "Controller" expose une méthode appelée "phoneIsComplete ()", qui à son tour dépend de la méthode "lookupPhone ()" de DataProviderProxy, qui à son tour dépend de la méthode "lookupPhone ()" de DataProvider.

Maintenant, vous pourriez gémir et penser "uggg ... cela ne me donne pas une vue d'ensemble du système - c'est juste des interactions individuelles à travers le système". Selon la sophistication du système, cela pourrait être une préoccupation valable (les systèmes simples peuvent certainement se débrouiller avec juste une collection de diagrammes de séquence). Donc, nous passons aux diagrammes structurels et nous regardons quelque chose comme un diagramme de classe statique:

http://www.f5systems.in/apnashoppe/education//img/chapters/uml_class_diagram.jpg

Les diagrammes de classes nous aident à comprendre deux choses importantes: la cardinalité et les types de relations de classe. Les classes peuvent être liées les unes aux autres de différentes manières: association, agrégation et composition. Techniquement parlant, il existe une différence entre les "relations de classe statiques" et les "relations d'instance". Cependant, en pratique, vous voyez ces lignes floues. La principale différence est que les relations de classe statiques n'incluent généralement pas la cardinalité. Regardons l'exemple ci-dessus et voyons ce que nous pouvons voir. Tout d'abord, nous pouvons voir que "Ordre spécial" et "Ordre normal" sont des sous-types d '"Ordres" (héritage). Nous pouvons également voir qu'un client a N commandes (qui peuvent être des «commandes normales», des «commandes» ou des «commandes spéciales») - l'objet client n'a pas t vraiment savoir. Nous pouvons également voir un certain nombre de méthodes (dans la moitié inférieure de chaque boîte de classe) et de propriétés (la moitié supérieure de chaque boîte de classe).

Je pourrais continuer à parler des diagrammes UML pendant longtemps, mais ce sont les bases. J'espère que cela aide.

TLDR; Choisissez un diagramme comportemental et un diagramme UML structurel, apprenez à le créer et vous accomplirez ce que vous essayez d'accomplir.

Si vous avez de la difficulté à décrire des choses comme le fonctionnement de la structure de haut niveau de votre programme et le bon fonctionnement des classes, considérez la maxime suivante:

A picture is worth a thousand words.

La façon dont vous peignez une image sur le code consiste à fournir des exemples de code. Beaucoup d'entre eux. C'est ainsi que vous créez un nouveau client (code). C'est ainsi que vous traitez une commande (code). Non seulement cela donne au consommateur de votre code un point de départ, mais il illustre également comment tous les objets se connectent et interagissent. Si j'utilisais votre code, la plus grande faveur que vous pourriez me faire serait de fournir de nombreux exemples de code.

La façon dont vous peignez une image pour un utilisateur final consiste à fournir des captures d'écran. Beaucoup d'entre eux. Capture d'écran après capture d'écran qui illustre, si vous voulez faire cette tâche, c'est ce que vous faites en premier, c'est ce que vous faites ensuite, etc.

L'UML, bien que souvent utilisé pour modéliser un logiciel avant sa création, pourrait être utile. Il existe plusieurs diagrammes différents qui illustrent les cas d'utilisation, les interactions de classe, etc. etc. Vous pouvez en voir plus ici .

Je trouve https://www.websequencediagrams.com/ un outil extrêmement utile pour décrire l'interaction entre les composants d'une application ou entre les services d'une application distribuée. Cela facilite simplement le processus de création et de maintenance des diagrammes de séquence UML.

La bonne chose est que si vous considérez chaque ligne de vie comme l'interface ou la classe dans votre application (je modélise généralement les gros joueurs), chaque ligne entrant dans cette classe représente une méthode que vous devez prendre en charge.

De plus, il existe des options de téléchargement pour obtenir l'image. Il existe également des moyens simples d'intégrer le diagramme dans un wiki. C'est donc un excellent outil de communication pour décrire l'interaction entre des composants ou des services dans un système, ainsi que pour communiquer cela avec l'équipe.