Background: i miei collaboratori e io stiamo scrivendo un articolo per un diario accademico. Nel corso della nostra ricerca, abbiamo scritto un programma di simulazione in Java. Vogliamo rendere il programma di simulazione liberamente disponibile per essere utilizzato da altri. Abbiamo deciso di ospitare il codice su un repository GitHub. Per facilitare l'utilizzo da parte di altri, vogliamo scrivere una buona documentazione per il nostro programma, tra cui:

• Javadocs per ogni classe e metodo
• Come usare il codice
• Descrivere la struttura di alto livello del codice

La mia domanda di alto livello è: potresti fornire un buon esempio delle parole e dei diagrammi che possono essere usati per descrivere la struttura di alto livello di un programma? Questo include sotto-domande:

1. Come mostriamo quali classi sono contenute in quali pacchetti?
2. Come mostriamo quali pacchetti dipendono da altri pacchetti?
3. Come mostriamo come gli oggetti / le classi nel programma lavorano insieme?
4. Abbiamo cercato di utilizzare i principi di progettazione basati sul dominio nella progettazione del mio codice. Come mostriamo la corrispondenza tra gli oggetti nel dominio e i particolari file di codice sorgente che codificano questi oggetti? (Vedi la mia descrizione "linguaggio onnipresente" del progetto qui sotto.)

Quello che ho fatto finora

Linguaggio ubiquitario

Mettiamo una descrizione "linguaggio onnipresente" del codice in un file ubiquitous-language.md, i contenuti di seguito.

Lo scopo di questo progetto è quello di studiare il rendimento di una politica di rifornimento in una semplice catena di approvvigionamento con un'unica struttura, con diversi modelli di lead time, ritardi nei rapporti e modelli di domanda.

In ogni periodo, si verificano i seguenti eventi:

1. Se una spedizione è programmata per arrivare alla struttura nel periodo corrente, il livello di inventario della struttura viene incrementato di X unità.
2. Se la pianificazione indica che il periodo corrente è un periodo di report, la struttura invia un report al fornitore . Il fornitore può ricevere il rapporto istantaneamente o con un ritardo di diverse settimane, come specificato dal programma .
3. Se il fornitore ha ricevuto un rapporto , quindi in base alla politica di rifornimento , calcolerà una quantità di rifornimento di X unità. Una spedizione di X unità del prodotto sarà programmata per arrivare dopo un termine di l periodi.
4. I clienti arrivano alla struttura e richiedono X unità del prodotto. Qualsiasi richiesta non soddisfatta viene persa.

Struttura del codice sorgente

Inseriamo una descrizione "di alto livello" incompleta del codice in un file structure.md, contenuto sotto.

Struttura a livello di pacchetto

Al livello più alto, il codice sorgente è organizzato in tre pacchetti

• com.gly.sfs La classe principale con il mainmetodo risiede in questo pacchetto.
• com.gly.sfs.model Le classi del modello di dominio risiedono in questo pacchetto.
• com.gly.sfs.util Le classi di supporto risiedono in questo pacchetto.

Normalmente , useresti UML per lo scopo che descrivi. UML sostanzialmente si divide in due tipi di diagrammi: strutturale e comportamentale.

I diagrammi strutturali includono: composizione, distribuzione, pacchetto, classe, oggetto e componente. I diagrammi comportamentali includono: sequenza, macchina a stati, comunicazione, caso d'uso, attività e panoramica delle interazioni.

A seconda di ciò che stai cercando di trasmettere, scegli alcuni di questi diagrammi che rappresentano al meglio tutto ciò che stai cercando di trasmettere, e così facendo permetti alla conversazione di "salire di livello". Invece di parlare di metodi, parametri e codice, stai parlando di sequenze di interazioni, dipendenze di classi statiche o di qualunque diagramma tu scelga di creare.

Ho allegato un esempio di un diagramma di sequenza (uno dei diagrammi comportamentali). Personalmente mi piace il diagramma di sequenza perché si trova proprio nel mezzo del processo di artefatto di progettazione - all'incirca un numero uguale di diagrammi dipende da come si aspetta come input. Trovo che i diagrammi di input siano in genere "compresi" comunque, o il diagramma di sequenza implica già la loro esistenza. Tuttavia, a volte faccio sia diagrammi di classi statici che diagrammi di sequenza (uno schema strutturale e uno comportamentale).

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

Non ho mai visto questo diagramma prima in vita mia, ma posso dire una serie di cose su questo sistema. Esistono quattro componenti principali (i nomi nel sistema, in genere le classi): Visualizza, Controller, Proxy dati e Provider di dati. Le frecce sono "comportamenti" o invocazioni di metodi. Un diagramma di sequenza è sostanzialmente buono per mostrare una singola importante interazione tra un gruppo di componenti. Hai un diagramma di sequenza per ciascun flusso importante nel tuo sistema. Da questo particolare diagramma posso dire che "Controller" espone un metodo chiamato "phoneIsComplete ()", che a sua volta dipende dal metodo "lookupPhone ()" di DataProviderProxy, che a sua volta dipende dal metodo "lookupPhone ()" di DataProvider.

Ora, potresti lamentarti e pensare "uggg ... questo non mi dà una visione d'insieme del sistema, ma solo interazioni individuali attraverso il sistema". A seconda della raffinatezza del sistema, questa potrebbe essere una preoccupazione valida (i sistemi semplici possono sicuramente cavarsela con solo una raccolta di diagrammi di sequenza). Quindi, passiamo ai diagrammi strutturali e guardiamo qualcosa di simile a un diagramma di classe statico:

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

I diagrammi di classe ci aiutano a capire due cose importanti: cardinalità e tipi di relazione di classe. Le classi possono essere correlate tra loro in diversi modi: associazione, aggregazione e composizione. Tecnicamente parlando, c'è una differenza tra "relazioni di classe statiche" e "relazioni di istanza". Tuttavia, in pratica vedi queste linee sfocate. La differenza principale è che le relazioni di classe statiche di solito non includono la cardinalità. Diamo un'occhiata all'esempio sopra e vediamo cosa possiamo vedere. In primo luogo, possiamo vedere che "Ordine speciale" e "Ordine normale" sono sottotipi di "Ordini" (eredità). Possiamo anche vedere che un cliente ha N ordini (che possono essere "Ordini normali", "Ordini" o "Ordini speciali") - l'oggetto Cliente non lo so davvero. Possiamo anche vedere un numero di metodi (nella metà inferiore di ogni riquadro di classe) e proprietà (metà superiore di ogni riquadro di classe).

Potrei continuare a parlare di diagrammi UML per molto tempo, ma questa è la base. Spero che questo aiuti.

TLDR; Scegli un diagramma UML comportamentale e uno strutturale, impara come crearlo e realizzerai ciò che stai cercando di realizzare.

Se hai difficoltà a descrivere cose come il funzionamento della struttura di alto livello del tuo programma e come le classi funzionano bene insieme, considera la seguente massima:

A picture is worth a thousand words.

Il modo in cui dipingi un'immagine sul codice è quello di fornire esempi di codice. Molti di loro. Ecco come si crea un nuovo cliente (codice). Ecco come elaborare un ordine (codice). Ciò non solo offre al consumatore del tuo codice un punto di partenza, ma illustra come tutti gli oggetti si collegano e interagiscono. Se stavo usando il tuo codice, il più grande favore che potresti farmi è quello di fornire molti esempi di codice.

Il modo in cui dipingi un'immagine per un utente finale è quello di fornire schermate. Molti di loro. Schermata dopo immagine che illustra, se si desidera eseguire questa attività, questo è ciò che si fa per primo, questo è ciò che si fa dopo, ecc.

UML, sebbene spesso utilizzato per modellare il software prima della sua creazione, potrebbe essere utile. Esistono diversi diagrammi che illustrano casi d'uso, interazioni di classe, ecc. Ecc. Puoi vedere di più qui .

Trovo https://www.websequencediagrams.com/ uno strumento estremamente utile per descrivere l'interazione tra componenti all'interno di un'applicazione o tra servizi in un'applicazione distribuita. Semplifica molto il processo di creazione e gestione dei diagrammi di sequenza UML.

La cosa bella è che se consideri che ogni linea di vita è l'interfaccia o la classe nella tua applicazione (di solito modello solo i grandi giocatori), ogni linea che fluisce in quella classe rappresenta un metodo che devi supportare.

Inoltre, ci sono alcune opzioni di download per ottenere l'immagine. Ci sono anche alcuni semplici modi per incorporare il diagramma in una wiki. Quindi è un ottimo strumento di comunicazione per descrivere l'interazione tra componenti o servizi in un sistema, oltre a comunicarlo con il team.