Как вести поддержку/документацию монстр-проекта?

Question

[para_noir_in_my_box]

Добрый день.

Имеется веб-мотор, на котором есть куча сайтов.
Ведется постоянная доработка проекта.
Изначально проект был очень красивый и все сайты работали одинаково.
Но постоянно один,другой,третий сайт просят уникальный функционал.
Плюс идет добавление дополнительного общего функционала.

В итоге:
Имеется функционирующий и не очень костыльный проект (на мой взгляд).
Но через некоторое время никто не может вспомнить как все работает. В общих чертах все знают, но мелочей - нет.
Например - кто изменяет статус пользователя? Понятно, что есть компонент непосредственно управляющий таблицей и тд, но кто его использует? В какие моменты? консольный скрипт, может быть апи? а может быть пользователь еще не авторизовался? или его заблокировали?

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

Comments

[alex4answ]

документация кода + UML + логи , как вы еще себе представляете это ?

[para_noir_in_my_box]

Я и хотел узнать как люди себе это представляют =)
Думаю что код документировать не нужно (если я правильно понимаю что имеется ввиду)
Лучше обойтись описанием компонентов и добавить теги, например #userstatus и потом искать по ним.
Но заранее я не могу сказать какие теги мне понадобятся в будущем. Какие логи мне понадобятся в будущем.
Как понять что стоит логировать а что нет? Сейчас стоит вопрос - кто меняет статус? завтра встанет вопрос - почему у этой новости нет названия? или доверять ли пользователю, что он не трогал этот раздел сайта, а в нем пропала информация?

[para_noir_in_my_box]

Может быть стоит еще описывать именно сценарии, кто запускается, какой результат.

[Дмитрий]

документация кода + UML + git + стандартизация кода + грамотный тех.лид

[Валентин]

Есть такая дисциплина - управление конфигурацией.

[para_noir_in_my_box]

Валентин, Можете скинуть ссылки на пару примеров того, что получается в итоге? Или как-то кратко описать, чтобы было понятнее стоит изучить это или нет))

Answer 1

[Северное Сияние]

Переписать всё заново

Comments

[para_noir_in_my_box]

Это не сурьезно =)

[para_noir_in_my_box]

Допустим вы решили переписать все заново - как бы вы предусмотрели в новом проекте подобные моменты?

[Северное Сияние]

para_noir_in_my_box, не серьезно было делать это:

постоянно один,другой,третий сайт просят уникальный функционал.

надо было либо разделять проекты, либо не трогать.

[Антон Тихомиров]

Ахахахаха, блин, чот даже смешно стало)))

Answer 2

[Boris Köln]

У вас два разных вопроса.

кто его использует? В какие моменты? консольный скрипт, может быть апи?

Должна быть правильная структура проекта.
Framework и другие сторонние библиотеки - в папке vendor или node_modules
Ваш движок - в другой папке.
Каждый сайт - в отдельной папке. Если у него есть свой функционал или переопределение базового - наследование от базового.

Тогда ответы на ваши вопросы очень простые:
* какой именно функционал - открыть наследуемый класс. В IDE есть иконка-подсказка.
* кто использует - в IDE есть "Find usages"

а может быть пользователь еще не авторизовался? или его заблокировали?

Для этого должно быть логирование. Если речь про скрипты, то git. Если про изменение в БД, то и триггеры на уровне БД или запрет прямого доступа к БД, а работа только через модель и логирование.

Comments

[para_noir_in_my_box]

В проекте код организован хорошо (на мой взгляд).
Логирование да, надо выделить из этого вопроса. Но опять же вопрос про логирование - что логировать?
Допустим доступ к базе идет только через "модели". Если я просто буду логировать "Запись изменена" - это ничего не даст. Важнее знать - по какой причине она изменена, какой сценарий был запущен. Такое впечатление что придется в начале каждого метода каждого класса писать строку кода с логированием но это как-то странно.

Answer 3

[Толстый Лорри]

Разница должна быть обязательно расширением базовой функциональности (статически - через наследование), либо работать через стандартизированный интерфейс (динамически - API для плагинов).
Костыли с кучей if лучше заменять полиморфизмом, используя IoC via DI и идею паттерна Стратегия.

Детальную девелоперскую документацию вести нет смысла, как показывает практика - ее трудно поодерживать. Можно завести вики или даже документы, в общих чертах описывающих работу тех или иных неочевидных узлов.
С точки зрения логики работы приложения, в сурёзных конторах QA пишут тест-кейсы, которые фиксируют требования. Это бывает полезно, чтобы освежить память. (тест-кейсы не устаревают, ибо каждый релиз прогоняется полный регрессионный цикл)

Comments

[para_noir_in_my_box]

Да, новый функционал вынесен в отдельные места и имеются DI ветвления в зависимости от.
Если нет смысла вести детальную документацию, то кто будет знать все о проекте?)) Я верю что наш проект - это миллиметр по сравнению с проектами в крупных компаниях. Как у них обстоят дела тогда?)

[Толстый Лорри]

para_noir_in_my_box,

Если нет смысла вести детальную документацию, то кто будет знать все о проекте?

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

По моему опыту, достаточно знать основные грабли, какие есть в проекте (или обильно откомментировать такие единичные неочевидные места, где с первого взгляда не ясно: "Зачем?"). Все остальное добывается пристальным взглядом в код с необходимой глубиной погружения в абстракции. Знающие люди могут ускорить эти изыскания, поэтому идеальный баланс где-то между bus-факторной безопасностью и командами-специалистами в своих областях. То есть есть какая-то основная область, но примерно представляют себе архитектуру взаимодействия других модулей и при необходимости могут и туда залезть. Кадры - наше всё.

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

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

Answer 4

[DarkTM]

Правильная архитектура, она сама себя документирует, так как отражает происходящие процессы. Ведение документации закладывается изначально в проект. В каждом языке есть свой инструмент для автоматической генерации док. Хотя правильно сразу делать гайдлайн + общая модель всех бизнес процессов, плюс нарезка на микросервисы.
В вашем случае - уже поздно пить боржоми когда печень сдохла. Так как проект вышел из под контроля и ситуации, когда есть хоть кто-то, кто может описать работу вашего сервиса. И вам написали один из двух выходов - переписывать с нуля. Второй выход - форкать, садить человек пять и пусть разбираются в коде и как оно работает, заодно и документируют. Других средств просто нет.
Хотя нет вру, вру. есть. Написать нейронку, распарсить код, сделать AST, скормить нейронке и пусть задокументирует. Стоить это будет думаю больше чем весь ваш проект в принципе.

Comments

[Vadim Priluzkiy]

Ну зато нейронку можно будет начать продавать. ;-)

[para_noir_in_my_box]

Я и еще пара людей могут ответить на нужные вопросы (например перечисленные в теме), но на это уходит время + нет 100% уверенности, что я чего-то не забыл.
Для уверенности, допустим решили сделать документацию. Но вопрос - как она должна выглядеть, чтобы я смог по ней найти нужную тему? Расписывать классы и их методы - пустая трата, думаю надо расписать сценарии. Но на это надо потратить время + поддерживать постоянно...

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