Словарь предметной области

Мне много раз приходилось знакомиться с новыми для себя проектами. Для ускорения понимания проекта и кода я каждый раз начинал с одного и того же: составлял словарь предметной области.

И это не про графоманию, а про необходимость и реально рабочий инструмент – базис Domain-Driven Design – Ubiquitous Language. Чтобы общаться на иностранном языке, нужно пополнять словарный запас.

Вы можете обратиться к трудам Эрика Эванса, но не найдете там того, как именно должно выглядеть описание языка. Поэтому делюсь своим способом оформления и использования словаря.

Оформление

Формат словаря прост – это таблица из трёх колонок:

• Термин – как должно быть.
• Синонимы – как на самом деле в коде и моделях.
• Определение – очень краткое толкование простым языком.

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

Например:

• Термин: Problem
• Синонимы: Task, Задача
• Определение: Задача по программированию

Использование

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

• В коде нет единства именования. Не страшно, но это делает код более хаотичным и менее понятным; провоцирует развитие беспорядка и появление ошибок. Это сродни тому, когда иностранец говорит с акцентом, а абориген его плохо понимает.
• Модель имеет неточность или какое-то упрощение. К сожалению, это распространенная проблема, и синонимы часто скрывают какие-то бизнес-процессы, с которыми вы ещё не столкнулись или не выявили. Подобные ошибки могут обойтись очень дорого, но словарь позволяет заметить эту проблему заранее.

Словарь не всегда прямолинеен: “термин – синонимы”. Бывает, когда разные термины по факту имеют один и тот же синоним. И это уже очень серьёзный сигнал!

Например, в одном из проектов перечисление (enum) объединяло в один список два разных набора, которые использовались в двух разных бизнес-контекстах. Как например, если бы вы объединили в один список месяцы и дни недели. В реальной жизни эти списки используются по отдельности, но в коде они были объединены в один, который интерпретировался в каждой ситуации по-своему. Не трудно догадаться, какие проблемы в коде может породить подобное. Самое безобидное – это увеличение цикломатической сложности из-за обилия проверок и фильтров.

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

Хранение

Словарь предлагаю хранить в Markdown-файле в корне git-репозитория. И пусть корневой readme.md имеет ссылку на этот файл где-то в самом начале.

Не рекомендую использовать внешние wiki вроде Confluence по многим причинам. Во-первых, словарь должен отражать текущее положение дел, следовательно, требует версионирования. Во-вторых, нет необходимости доступа к внешним ресурсам, что удобно как для человека, так и для машины (AI). Хотите словарь в wiki – сделайте его копию, но оригинал пусть будет в репозитории.

Достоинства

• Ускорение входа в проект. Это реально так: 30 минут на освоение словаря и вы готовы читать и понимать код и диаграммы, разговаривать на “птичьем” языке с коллегами по цеху.
• Обнаружение неточностей в моделях. Словарь позволяет вскрывать проблемы моделирования и скрытые концепты.
• Помощь в унификации именования в коде. В идеале все синонимы должны стать терминами.
• Реальное подспорье для онбординга и AI-агентов. Думаю, что это становится крайне важно в современных реалиях.

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

И пусть ваш код говорит без акцента!