Существует ли стандарт для документирования архитектуры высокого уровня программы?

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

Теперь я сталкиваюсь с программой, которая перерастает мои способности запоминать различные взаимодействия между

• сам код
• индексы в базе данных
• взаимодействие между различными модулями (рабочий код ядра и библиотечный)

Моя текущая документация - это доска, где у меня есть все виды полей и стрелок, которые указывают на код, на индексы базы данных, на выполняемые действия, на изменение состояния и т. Д. Просто для справки, фрагмент беспорядка:

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

Какие ключевые слова мне следует искать (общие попытки «стандартов архитектуры программного обеспечения для документов» и подобные изменения обычно приводили к созданию программного обеспечения для рабочих процессов или построению систем САПР с архитектурой).

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

Нет единого стандарта, которого все придерживаются. Программные проекты могут сильно различаться (подумайте: helloworld.py против кода в космическом челноке).

Один из самых распространенных методов - использование модели 4 + 1 . Вместо того, чтобы пытаться втиснуть все в единый стиль документа, эта методология разбивает дизайн на пять компонентов:

• Развитие зрения
• Логический вид
• Физический вид
• Процесс зрения
• Сценарии

Различные взгляды описывают продукт с четырех разных точек зрения. Сценарии, в которых живут варианты использования, описывают взаимодействие других представлений.

Примечание. Это концептуальная модель, не привязанная к какому-либо конкретному инструменту.

Вы можете прочитать больше здесь:

1. 4 + 1 модель архитектурного вида (википедия)
2. Архитектурные планы - модель представления программного обеспечения «4 + 1» (документ IEEE - pdf)

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

Если вы ищете рабочий, прагматичный способ документирования высокоуровневых архитектур, я предлагаю ознакомиться с диаграммами потоков данных . Они просты для понимания и имеют то преимущество, что они могут масштабироваться до различных уровней абстракций. Я нашел их наиболее полезными для документирования различных видов систем. Жаль, что они не нашли свой путь в UML, но тем не менее вы найдете множество инструментов - даже бесплатных, таких как Dia или DrawIO - для создания этих диаграмм.

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

Унифицированный язык моделирования (UML) - это универсальный язык разработки для моделирования в области разработки программного обеспечения, предназначенный для обеспечения стандартного способа визуализации проектирования системы.

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

Я видел несколько моделей UML-монстров, и, честно говоря, они не делают для меня ничего, что код не может сделать, и делают это лучше.