Фон: мои сотрудники и я пишем статью для академического журнала. В ходе нашего исследования мы написали программу моделирования на Java. Мы хотим сделать программу симуляции свободно доступной для использования другими. Мы решили разместить код в репозитории GitHub. Чтобы другим было легко пользоваться, мы хотим написать хорошую документацию для нашей программы, в том числе:

• Javadocs для каждого класса и метода
• Как использовать код
• Описание высокоуровневой структуры кода

Мой высокоуровневый вопрос: не могли бы вы привести хороший пример слов и диаграмм, которые можно использовать для описания высокоуровневой структуры программы? Это включает в себя подвопросы:

1. Как мы показываем, какие классы содержатся в каких пакетах?
2. Как мы показываем, какие пакеты зависят от других пакетов?
3. Как мы показываем, как объекты / классы в программе работают вместе?
4. Мы постарались использовать принципы проектирования на основе предметной области при разработке моего кода. Как мы показываем соответствие между объектами в домене и конкретными файлами исходного кода, кодирующими эти объекты? (См. Мое «повсеместное выражение» описания проекта ниже.)

Что я сделал до сих пор

Вездесущий язык

Мы помещаем описание кода «вездесущего языка» в файл ubiquitous-language.md, содержание которого приведено ниже.

Цель этого проекта состоит в том, чтобы изучить, насколько хорошо политика пополнения запасов работает в простой цепочке поставок с одним средством, в рамках различных моделей сроков поставки, задержек отчетов и моделей спроса.

В каждом периоде происходят следующие события:

1. Если отгрузка запланирована на объект в текущем периоде, то уровень запасов объекта увеличивается на X единиц.
2. Если график показывает , что текущий период является отчетным периодом, то объект представляет отчет к поставщику . Поставщик может получить отчет немедленно, или с задержкой в несколько недель, как указано в расписании .
3. Если поставщик получил отчет , то в соответствии с политикой пополнения он рассчитает количество пополнения X единиц. Пересылка рентгеновских единиц продукта будет назначено прибыть после заблаговременности л периодов.
4. Клиенты прибывают на объект и требуют X единиц товара. Любой неудовлетворенный спрос теряется.

Структура исходного кода

Мы поместили неполное высокоуровневое описание кода в файл structure.md, содержание которого приведено ниже.

Структура уровня пакета

На высшем уровне исходный код организован в три пакета

• com.gly.sfs Основной класс с mainметодом находится в этом пакете.
• com.gly.sfs.model Классы модели предметной области находятся в этом пакете.
• com.gly.sfs.util Вспомогательные классы находятся в этом пакете.

Обычно вы используете UML для целей, которые вы описываете. UML в основном разбивается на два типа диаграмм: структурные и поведенческие.

Структурные диаграммы включают в себя: состав, развертывание, пакет, класс, объект и компонент. Поведенческие диаграммы включают в себя: последовательность, конечный автомат, связь, сценарий использования, активность и обзор взаимодействия.

В зависимости от того, что вы пытаетесь передать, вы выбираете несколько из этих диаграмм, которые лучше всего представляют то, что вы пытаетесь передать, и тем самым вы позволяете разговору «подняться на уровень». Вместо того чтобы говорить о методах, параметрах и коде, вы говорите о последовательности взаимодействий, статических зависимостях классов или любых диаграммах, которые вы выбираете для создания.

Я приложил пример диаграммы последовательности (одна из диаграмм поведения). Мне лично нравится диаграмма последовательности, потому что она находится прямо в середине процесса проектирования артефактов - примерно столько же диаграмм зависит от нее, как ожидается в качестве входных данных. Я считаю, что входные диаграммы, как правило, «понимают» в любом случае, или диаграмма последовательности уже предполагает их существование. Однако иногда я делаю и статические диаграммы классов, и диаграммы последовательности (одна структурная и одна поведенческая диаграмма).

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

Я никогда не видел эту диаграмму раньше в своей жизни, но я могу рассказать кое-что об этой системе. Существует четыре основных компонента (существительные в вашей системе - обычно это классы): представление, контроллер, прокси-сервер данных и поставщик данных. Стрелки - это «поведение» или вызов метода. Диаграмма последовательности в основном хороша для демонстрации одного важного взаимодействия между кучей компонентов. У вас есть одна диаграмма последовательности для каждого важного потока в вашей системе. Из этой конкретной диаграммы я могу сказать, что «Контроллер» предоставляет метод под названием phoneIsComplete (), который, в свою очередь, зависит от метода lookupPhone () DataProviderProxy, который, в свою очередь, зависит от метода lookupPhone () DataProvider.

Теперь вы можете стонать и думать: «Угу ... это не дает мне общую картину системы - это просто индивидуальное взаимодействие через систему». В зависимости от сложности системы это может быть серьезной проблемой (простые системы могут определенно обойтись только с помощью набора диаграмм последовательности). Итак, мы переходим к структурным диаграммам и смотрим на что-то вроде статической диаграммы классов:

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

Диаграммы классов помогают нам понять две важные вещи: количество элементов и типы отношений классов. Классы могут быть связаны друг с другом по-разному: ассоциация, агрегация и композиция. Технически говоря, есть разница между «отношениями статического класса» и «отношениями экземпляра». Однако на практике вы видите эти линии размытыми. Основное отличие состоит в том, что статические классовые отношения обычно не включают в себя количество элементов. Давайте посмотрим на пример выше и посмотрим, что мы можем увидеть. Во-первых, мы видим, что «Специальный заказ» и «Нормальный заказ» являются подтипами «Заказы» (наследование). Мы также видим, что у одного Клиента есть N заказов (это могут быть «Обычные заказы», ​​«Заказы» или «Специальные заказы») - объект «Клиент» не ' Я действительно знаю. Мы также можем увидеть ряд методов (в нижней половине каждого блока класса) и свойств (в верхней половине каждого блока класса).

Я мог бы продолжать говорить о диаграммах UML в течение долгого времени, но это основы. Надеюсь, это поможет.

TLDR; Выберите одну поведенческую и одну структурную UML-диаграмму, узнайте, как ее создать, и вы получите то, чего пытаетесь достичь.

Если вам трудно описать такие вещи, как структура высокого уровня вашей программы и то, как классы хорошо работают вместе, рассмотрите следующий принцип:

A picture is worth a thousand words.

То, как вы рисуете картину о коде, - это предоставление примеров кода. Многие из них. Вот как вы создаете нового клиента (код). Вот как вы обрабатываете заказ (код). Это не только дает потребителю кода возможность для начала, но и показывает, как все объекты соединяются и взаимодействуют. Если бы я использовал ваш код, самое большое преимущество, которое вы могли бы мне оказать, - это предоставить множество примеров кода.

То, как вы рисуете картинку для конечного пользователя, - это предоставление скриншотов. Многие из них. Снимок экрана за снимком экрана, на котором показано, что если вы хотите выполнить эту задачу, это то, что вы делаете в первую очередь, это то, что вы делаете дальше, и т. Д.

UML, хотя часто используется для моделирования программного обеспечения до его создания, может быть полезен. Есть несколько различных диаграмм, которые иллюстрируют сценарии использования, взаимодействия классов и т. Д. И т. Д. Вы можете увидеть больше об этом здесь .

Я считаю https://www.websequencediagrams.com/ чрезвычайно полезным инструментом для описания взаимодействия между компонентами в приложении или между службами в распределенном приложении. Это значительно упрощает процесс создания и обслуживания диаграмм последовательности UML.

Приятно то, что если вы считаете, что каждая линия жизни является интерфейсом или классом в вашем приложении (я обычно просто моделирую крупных игроков), то каждая строка, проходящая в этот класс, представляет метод, который вы должны поддерживать.

Кроме того, есть несколько вариантов загрузки, чтобы получить изображение. Есть также несколько простых способов встроить диаграмму в вики. Таким образом, это отличный инструмент коммуникации, чтобы описать взаимодействие между компонентами или сервисами в системе, а также сообщить об этом команде.