Antecedentes: Meus colaboradores e eu estamos escrevendo um artigo para uma revista acadêmica. No decorrer de nossa pesquisa, escrevemos um programa de simulação em Java. Queremos tornar o programa de simulação disponível gratuitamente para uso de outras pessoas. Decidimos hospedar o código em um repositório do GitHub. Para facilitar o uso de outras pessoas, queremos escrever uma boa documentação para o nosso programa, incluindo:

• Javadocs para cada classe e método
• Como usar o código
• Descrevendo a estrutura de alto nível do código

Minha pergunta de alto nível é: você poderia fornecer um bom exemplo das palavras e diagramas que podem ser usados ​​para descrever a estrutura de alto nível de um programa? Isso inclui como sub-perguntas:

1. Como mostramos quais classes estão contidas em quais pacotes?
2. Como mostramos quais pacotes dependem de outros pacotes?
3. Como mostramos como os objetos / classes no programa funcionam juntos?
4. Tentamos usar princípios de design controlados por domínio no design do meu código. Como mostramos a correspondência entre os objetos no domínio e os arquivos de código-fonte específicos que codificam esses objetos? (Veja minha descrição em "linguagem onipresente" do projeto abaixo.)

O que eu fiz até agora

Linguagem onipresente

Colocamos uma descrição "linguagem onipresente" do código em um arquivo ubiquitous-language.md, conteúdo abaixo.

O objetivo deste projeto é estudar o desempenho de uma política de reabastecimento em uma cadeia de suprimentos simples com uma única instalação, sob diferentes modelos de lead time, atrasos de relatórios e modelos de demanda.

Em cada período, ocorrem os seguintes eventos:

1. Se uma remessa estiver programada para chegar à instalação no período atual, o nível de estoque da instalação será incrementado por X unidades.
2. Se o cronograma indicar que o período atual é um período de relatório, a instalação envia um relatório ao fornecedor . O fornecedor pode receber o relatório instantaneamente, ou com um atraso de várias semanas, conforme especificado na programação .
3. Se o fornecedor recebeu um relatório , com base na política de reabastecimento , ele calculará uma quantidade de reabastecimento de X unidades. Uma remessa de X unidades do produto será agendada para chegar após um prazo de l períodos.
4. Os clientes chegam às instalações e exigem X unidades do produto. Qualquer demanda não atendida é perdida.

Estrutura do código fonte

Colocamos uma descrição "de alto nível" incompleta do código em um arquivo structure.md, conteúdo abaixo.

Estrutura em nível de pacote

No nível mais alto, o código fonte é organizado em três pacotes

• com.gly.sfs A classe principal com o mainmétodo reside neste pacote.
• com.gly.sfs.model As classes de modelo de domínio residem neste pacote.
• com.gly.sfs.util As classes auxiliares residem neste pacote.

Normalmente , você usaria a UML para a finalidade que você descreve. A UML basicamente se divide em dois tipos de diagramas: estrutural e comportamental.

Os diagramas estruturais incluem: composição, implantação, pacote, classe, objeto e componente. Os diagramas comportamentais incluem: sequência, máquina de estado, comunicação, caso de uso, atividade e visão geral da interação.

Dependendo do que você está tentando transmitir, você escolhe alguns desses diagramas que melhor representam o que você está tentando transmitir e, ao fazer isso, permite que a conversa "suba de nível". Em vez de falar sobre métodos, parâmetros e código, você está falando sobre sequência de interações, dependências de classe estáticas ou quaisquer diagramas que você escolher criar.

Anexei um exemplo de um diagrama de sequência (um dos diagramas de comportamento). Pessoalmente, gosto do diagrama de sequência porque está bem no meio do processo de artefato de design - aproximadamente um número igual de diagramas depende dele, conforme espera como entrada. Acho que os diagramas de entrada geralmente são "entendidos" de qualquer maneira, ou o diagrama de sequência já implica sua existência. No entanto, às vezes eu faço ambos os diagramas de classe estáticos e de seqüência (um diagrama estrutural e um comportamental).

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

Nunca vi esse diagrama na minha vida, mas posso dizer várias coisas sobre esse sistema. Existem quatro componentes principais (os substantivos em seu sistema - geralmente as classes): View, Controller, Data Proxy e Data Provider. As setas são "comportamentos" ou invocações de métodos. Um diagrama de sequência é basicamente bom para mostrar uma única interação importante entre vários componentes. Você tem um diagrama de sequência para cada fluxo importante no sistema. Eu posso dizer neste diagrama em particular que "Controller" expõe um método chamado "phoneIsComplete ()", que por sua vez depende do método "lookupPhone ()" do DataProviderProxy, que por sua vez depende do método "lookupPhone ()" do DataProvider.

Agora, você pode gemer e pensar "uggg ... isso não me dá uma imagem grande do sistema - são apenas interações individuais através do sistema". Dependendo da sofisticação do sistema, isso pode ser uma preocupação válida (sistemas simples podem definitivamente se dar bem com apenas uma coleção de diagramas de sequência). Então, passamos para os diagramas estruturais e olhamos para algo como um diagrama de classe estático:

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

Os diagramas de classe nos ajudam a descobrir duas coisas importantes: cardinalidade e tipos de relacionamento de classe. As classes podem ser relacionadas entre si de diferentes maneiras: associação, agregação e composição. Tecnicamente falando, há uma diferença entre "relacionamentos de classe estáticos" e "relacionamentos de instância". No entanto, na prática, você vê essas linhas borradas. A principal diferença é que os relacionamentos estáticos de classe geralmente não incluem cardinalidade. Vamos dar uma olhada no exemplo acima e ver o que podemos ver. Primeiro, podemos ver que "Ordem Especial" e "Ordem Normal" são subtipos de "Ordens" (herança). Também podemos ver que um cliente possui N pedidos (que podem ser "pedidos normais", "pedidos" ou "pedidos especiais") - o objeto Cliente não realmente não sei. Também podemos ver vários métodos (na metade inferior de cada caixa de classe) e propriedades (metade superior de cada caixa de classe).

Eu poderia continuar falando sobre diagramas UML por um longo tempo, mas esse é o básico. Espero que ajude.

TLDR; Escolha um diagrama UML comportamental e um estrutural, aprenda como criá-lo e você realizará o que está tentando realizar.

Se você estiver com dificuldades para descrever coisas como a estrutura de alto nível do seu programa e como as classes funcionam bem juntas, considere a seguinte máxima:

A picture is worth a thousand words.

A maneira como você cria uma imagem sobre o código é fornecer exemplos de código. Muitos deles. É assim que você cria um novo cliente (código). É assim que você processa um pedido (código). Isso não apenas fornece ao consumidor do seu código um local para começar, como ilustra como todos os objetos se conectam e interagem. Se eu estivesse usando seu código, o maior favor que você poderia me fazer é fornecer vários exemplos de código.

A maneira como você pinta uma imagem para um usuário final é fornecer capturas de tela. Muitos deles. Captura de tela após captura de tela que ilustra, se você deseja executar esta tarefa, isto é o que você faz primeiro, isto é o que você faz em seguida, etc.

A UML, embora frequentemente seja usada para modelar o software antes de ser criado, pode ser útil. Existem vários diagramas diferentes que ilustram casos de uso, interações de classe etc. etc. Você pode ver mais sobre isso aqui .

Considero https://www.websequencediagrams.com/ uma ferramenta extremamente útil para descrever a interação entre componentes em um aplicativo ou entre serviços em um aplicativo distribuído. Isso facilita muito o processo de criação e manutenção de diagramas de sequência UML.

O bom é que, se você considerar cada linha de vida como a interface ou classe em seu aplicativo (eu geralmente apenas modelo os grandes jogadores), cada linha que flui para essa classe representa um método que você deve suportar.

Além disso, existem algumas opções de download para obter a imagem. Existem também algumas maneiras fáceis de incorporar o diagrama em um wiki. Portanto, é uma ótima ferramenta de comunicação para descrever a interação entre componentes ou serviços em um sistema, além de comunicar isso com a equipe.