Как правильно документировать разрастающуюся БД?

Question

[Kentavr16]

Вопрос из обрасти общих знаний. Пишу пэт, довольно амбициозный (не монстр, но функционала и фич хватает). Использую для БД mysql + ORM sequelize. И начал замечать, что сложность структуры БД неумолимо растет. Чувствую что скоро достигну того уровня, когда другой программист, открыв код, потратит много времени на то чтобы сообразить что куда в плане взаимоотношений. Если что-то менять - то прямо сейчас.
Знающие люди, подскажите как такие вопросы решаются на реальных проектах? Очень приветствую примеры из личного опыта. Интересуют как инструменты, так и методология/подходы.

Comments

[alexalexes]

что сложность структуры БД неумолимо растет.

Показывайте структуру БД, мы ее сейчас подрежем, переформатируем, научим в третью нормальную форму. Не будет проблем с восприятием.

[Kentavr16]

alexalexes, как бы не была нормализована бд, вопрос останется. Вот к примеру - есть базовые таблицы и миграции - пользователи, роли пользователей для авторизации, смежная таблица для их связи. Уже по 3 модели и таблицы миграции. Дальше есть небольшой форум. Добавляем таблицы постов, тем обсуждения и тегов для тем обсуждения, комментариев, настроек - это базовые, ещё есть подозрение на + 3-4 таблицы. Ну и т.д по каждому разделу сайта. Некоторые разделы именно благодаря нормализации будут иметь десяток+ таблиц. И вот новый кодер открывает это дело . Понятно что просмотрев все таблицы у него будет сложено представление о бд, и посматривая в них он сможет через энное время понять что к чему. Но неужели это и есть норма? Нет общепринятых инструментов для нормальной визуализации структуры или ведения документации, чтобы при открытии этого описания ему не нужно было бы листать/анализировать /перечитывать?

Answer 1

[Everything_is_bad]

ORM уже само по себе хорошая документация, а "сложность структуры БД неумолимо растет" больше про проблему проектирования базы.

Comments

[Kentavr16]

Да. Относительно "сырого" sql это уже хорошая документация. Но посмотри пожалуйста мой ответ на комментарий к вопросу, там я попытался объяснить , не буду дублировать.

[Everything_is_bad]

Kentavr16, текст или картинка, это уже субъективное, я вот код ORM описания, намного лучше воспринимаю, чем ERD. Кто хочет визуализацию, скорее всего поищет инструмент автоматического их создания из SQL или ORM.

[Kentavr16]

Everything_is_bad, вот это поищу с удовольствием. Странно что так мало инструментов и они настолько непопулярны.

Answer 2

[rPman]

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

Comments

[Kentavr16]

Спасибо за ответ. Основная проблема такого подхода в том что новому разработчику все же придется "сёрфить" по репозиторию туда-сюда, просто делать это ему будет проще. Я бы хотел иметь крепкую входную точку для изучения бд, самодостаточный документ. Возможно глупость, раз никто о таком не слышал.

[rPman]

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

В базах данных когда то философски предлагалось пользоваться GUI по описанию ER-диаграммы базы, где и документация, и графическое представление, а затем среда разработки компилирует это представление в реляционную модель физической базы данных. смутно помню такое было для oracle но к сожалению ни одного названия не вспоминается и не гуглится (возможно это была часть оралковского менеджера баз данных, но! не pl-sql developer).

[MaksimMukharev]

rPman, а как же миграции? Более, чем достаточно, чтобы отразить изменения.

[Kentavr16]

MaksimMukharev, так вопрос в читаемости и удобстве. Кода для сайта в одно полотно тоже достаточно чтобы разобраться что происходит. Назвать файлы с кодом осмысленно - лучше. Разбить на чистые функции ещё лучше. Добавить аннотации типам вообще круто и т.д. и т.п.
Просматривать все миграции для понимания происходящего в количестве десятков выглядит не самым оптимальным вариантом. Вот на уровне с "хорошо именованными файлами". Это не назовешь хорошей документацией.

Answer 3

[dmitriy]

1. Основная проблема документации ее поддержка. Когда документация отстает, то она больше мешает чем, помогает.
2. Автоматизация создания доки, помню, использовал Interprice Architect для автосоздания диаграмм бд, в принципе помогало, но боюсь что использовалось только мной
3. В обще кто то сказал что лучшая документация это код, поэтому соглашусь что если есть некий workflow по созданию бд, и есть миграции с описанием что делает та или иная таблица. Я использую Propel2 ORM там есть некий конфиг (chema.xml) которая описывает таблицы + разделения таблицы на пакеты/группы/контекст. Маленьким контекстом проще управлять.

Comments

[Kentavr16]

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