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

10

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

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

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

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

введите описание изображения здесь

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

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

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

WOJ
источник
гм UML и какой-то простой старый текст обычно
JK.
Если вы можете читать по-немецки, взгляните на arc42.de/template/index.html. Они показывают некоторые руководящие принципы для документирования архитектуры программного обеспечения.
Бернхард Хиллер
8
«Не надо делать это вообще», вероятно, ближе всего к стандарту.
whatsisname

Ответы:

13

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

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

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

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

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

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

  1. 4 + 1 модель архитектурного вида (википедия)
  2. Архитектурные планы - модель представления программного обеспечения «4 + 1» (документ IEEE - pdf)
Брайан Оукли
источник
Это очень хороший подход, спасибо. Отступив, можно подумать, что это довольно очевидно, но это очень помогает разъединить различные 4 + 1 фрагменты, которые у меня были все на одном графике.
WoJ
4

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

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

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

Док Браун
источник
Пакетные диаграммы? Диаграммы развертывания? Диаграммы компонентов?
Ник Кейли,
3
Честно говоря, куча коробок со стрелками может творить чудеса для передачи ряда конструктивных особенностей. Я предполагаю, что диаграммы компонентов попадают в эту категорию, но мои клиенты понимают поток данных с блоками, представляющими основные биты. Я согласен с Доком Брауном. Формальность UML не соответствует цели по назначению.
Берин Лорич
@NickKeighley: см. Мое редактирование.
Док Браун
@BerinLoritsch: ИМХО «куча прямоугольников со стрелками» характеризует типы диаграмм, упомянутые Ником Кейли. Однако на диаграммах потоков данных проводится четкое формальное различие между данными или группами / кластерами данных и процессами или компонентами, которые передают или преобразовывают эти данные. Это ничего, что я могу легко выразить с помощью любой из диаграмм UML.
Док Браун
1
Я должен признать, что иногда прибегаю к диаграммам потоков данных - особенно к тем, которые разрешают магазины. На самом деле диаграмма верхнего уровня, которая описывает нашу систему, по сути является DFD. Я все еще нахожу диаграммы Класса и Пакет полезными в некоторой степени. Я не обращаю особого внимания на «формальные» части UML.
Ник Кейли,
0

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


источник
Формальную спецификацию можно найти по адресу omg.org/spec/UML/2.5, но в Интернете есть множество полезных руководств.
Саймон Б.
2
Этот ответ является лишь частью вопроса, UML, безусловно, является правильным инструментом для моделирования, но сам по себе он не является полной документацией
Вальфрат,
3
Кто-нибудь очень часто использует UML?
Panzercrisis
эскизное. обратный инжиниринг.
Ник Кейли,
1
@Walfrat. это? В самом деле? У меня есть сомнения.
Док Браун
-3

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

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

Ник Кейли
источник
3
не отвечает на вопрос, вероятно, лучше, как комментарий к ответу SuperGirl.
Newtopian
1
Это решает вопрос. Я утверждаю, что ответ на вопрос - больше «Нет», чем раньше.
Ник Кейли