Antecedentes: mis colaboradores y yo estamos escribiendo un artículo para una revista académica. En el curso de nuestra investigación, escribimos un programa de simulación en Java. Queremos que el programa de simulación esté disponible gratuitamente para que otros lo usen. Hemos decidido alojar el código en un repositorio de GitHub. Para facilitar el uso de otros, queremos escribir buena documentación para nuestro programa, que incluye:

• Javadocs para cada clase y método
• Cómo usar el código
• Describir la estructura de alto nivel del código.

Mi pregunta de alto nivel es: ¿Podría proporcionar un buen ejemplo de las palabras y los diagramas que se pueden usar para describir la estructura de alto nivel de un programa? Esto incluye como subpreguntas:

1. ¿Cómo mostramos qué clases están contenidas en qué paquetes?
2. ¿Cómo mostramos qué paquetes dependen de otros paquetes?
3. ¿Cómo mostramos cómo funcionan juntos los objetos / clases en el programa?
4. Hemos tratado de usar principios de diseño basados ​​en dominios en el diseño de mi código. ¿Cómo mostramos la correspondencia entre los objetos en el dominio y los archivos de código fuente particulares que codifican estos objetos? (Vea la descripción de mi "lenguaje ubicuo" del proyecto a continuación).

Lo que he hecho hasta ahora

Lengua ubicua

Ponemos una descripción de "lenguaje ubicuo" del código en un archivo ubiquitous-language.md, contenido a continuación.

El propósito de este proyecto es estudiar qué tan bien funciona una política de reabastecimiento en una cadena de suministro simple con una sola instalación, bajo diferentes modelos de tiempo de entrega, retrasos en los informes y modelos de demanda.

En cada período, ocurren los siguientes eventos:

1. Si un envío está programado para llegar a la instalación en el período actual, entonces el nivel de inventario de la instalación se incrementa en X unidades.
2. Si el cronograma indica que el período actual es un período de informe, la instalación presenta un informe al proveedor . El proveedor puede recibir el informe instantáneamente o con un retraso de varias semanas, según lo especificado en el cronograma .
3. Si el proveedor ha recibido un informe , basado en la política de reabastecimiento , calculará una cantidad de reabastecimiento de X unidades. Se programará que llegue un envío de X unidades del producto después de un tiempo de espera de 1 período.
4. Los clientes llegan a las instalaciones y exigen X unidades del producto. Cualquier demanda no satisfecha se pierde.

Estructura del código fuente

Ponemos una descripción incompleta "de alto nivel" del código en un archivo structure.md, contenido a continuación.

Estructura de nivel de paquete

En el nivel más alto, el código fuente se organiza en tres paquetes.

• com.gly.sfs La clase principal con el mainmétodo reside en este paquete.
• com.gly.sfs.model Las clases de modelo de dominio residen en este paquete.
• com.gly.sfs.util Las clases de ayuda residen en este paquete.

Normalmente , usaría UML para el propósito que describe. UML básicamente se divide en dos tipos de diagramas: estructurales y de comportamiento.

Los diagramas estructurales incluyen: composición, implementación, paquete, clase, objeto y componente. Los diagramas de comportamiento incluyen: secuencia, máquina de estados, comunicación, caso de uso, actividad y visión general de interacción.

Dependiendo de lo que esté tratando de transmitir, elige algunos de estos diagramas que mejor representan lo que está tratando de transmitir, y al hacerlo, permite que la conversación "suba un nivel". En lugar de hablar sobre métodos, parámetros y código, estás hablando de una secuencia de interacciones, dependencias de clase estática o cualquier diagrama que elijas crear.

Adjunto un ejemplo de diagrama de secuencia (uno de los diagramas de comportamiento). Personalmente, me gusta el diagrama de secuencia porque está justo en el medio del proceso de artefactos de diseño: aproximadamente un número igual de diagramas depende de él como se espera como entrada. Encuentro que los diagramas de entrada son típicamente "entendidos" de todos modos, o el diagrama de secuencia ya implica su existencia. Sin embargo, a veces hago diagramas de clase estáticos y diagramas de secuencia (un diagrama estructural y otro de comportamiento).

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

Nunca antes había visto este diagrama en mi vida, pero puedo decir varias cosas sobre este sistema. Hay cuatro componentes principales (los sustantivos en su sistema, generalmente las clases): Vista, Controlador, Proxy de datos y Proveedor de datos. Las flechas son "comportamientos" o invocaciones de métodos. Un diagrama de secuencia es básicamente bueno para mostrar una única interacción importante entre un grupo de componentes. Tiene un diagrama de secuencia para cada flujo importante a través de su sistema. Puedo decir por este diagrama en particular que "Controlador" expone un método llamado "phoneIsComplete ()", que a su vez depende del método "lookupPhone ()" de DataProviderProxy, que a su vez depende del método "lookupPhone ()" de DataProvider.

Ahora, puede gemir y pensar "uggg ... esto no me da una idea general del sistema, son solo interacciones individuales a través del sistema". Dependiendo de la sofisticación del sistema, eso podría ser una preocupación válida (los sistemas simples definitivamente pueden funcionar con solo una colección de diagramas de secuencia). Entonces, pasamos a los diagramas estructurales y vemos algo así como un diagrama de clase estático:

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

Los diagramas de clase nos ayudan a descubrir dos cosas importantes: cardinalidad y tipos de relación de clase. Las clases pueden relacionarse entre sí de diferentes maneras: asociación, agregación y composición. Técnicamente hablando, hay una diferencia entre "relaciones de clase estáticas" y "relaciones de instancia". Sin embargo, en la práctica, estas líneas se ven borrosas. La principal diferencia es que las relaciones de clase estáticas no suelen incluir cardinalidad. Miremos el ejemplo anterior y veamos qué podemos ver. Primero, podemos ver que "Orden especial" y "Orden normal" son subtipos de "Órdenes" (herencia). También podemos ver que un cliente tiene N pedidos (que pueden ser "pedidos normales", "pedidos" u "pedidos especiales"); el objeto del cliente no Realmente lo sé. También podemos ver varios métodos (en la mitad inferior de cada cuadro de clase) y propiedades (mitad superior de cada cuadro de clase).

Podría seguir hablando de diagramas UML durante mucho tiempo, pero esto es lo básico. Espero que eso ayude.

TLDR; Elija un diagrama UML de comportamiento y uno estructural, aprenda a crearlo y logrará lo que está tratando de lograr.

Si tiene dificultades para describir cosas como cómo funciona la estructura de alto nivel de su programa y cómo funcionan bien las clases juntas, considere la siguiente máxima:

A picture is worth a thousand words.

La forma de pintar una imagen sobre el código es proporcionar ejemplos de código. Muchos de ellos. Así es como se crea un nuevo cliente (código). Así es como procesas un pedido (código). Esto no solo le da al consumidor de su código un lugar para comenzar, sino que ilustra cómo todos los objetos se conectan e interactúan. Si estuviera usando su código, el mayor favor que podría hacerme es proporcionar muchos ejemplos de código.

La forma de pintar una imagen para un usuario final es proporcionar capturas de pantalla. Muchos de ellos. Captura de pantalla tras captura de pantalla que ilustra, si quieres hacer esta tarea, esto es lo que haces primero, esto es lo que haces después, etc.

UML, aunque a menudo se usa para modelar software antes de crearlo, podría ser útil. Hay varios diagramas diferentes que ilustran casos de uso, interacciones de clase, etc., etc. Puede ver más sobre esto aquí .

Encuentro https://www.websequencediagrams.com/ una herramienta extremadamente útil para describir la interacción entre componentes dentro de una aplicación, o entre servicios en una aplicación distribuida. Simplemente hace que el proceso de crear y mantener diagramas de secuencia UML sea mucho más fácil.

Lo bueno es que, si considera que cada línea de vida es la interfaz o clase en su aplicación (generalmente solo modelo a los grandes jugadores), entonces cada línea que fluye hacia esa clase representa un método que debe admitir.

Además, hay algunas opciones de descarga para obtener la imagen. También hay algunas formas fáciles de incrustar el diagrama en una wiki. Por lo tanto, es una gran herramienta de comunicación para describir la interacción entre componentes o servicios en un sistema, así como para comunicar eso con el equipo.