Comments 26
Хм. Да, неактуальная документация, разрозненные куски требований и легаси боль любого проекта/продукта, которому больше полгодика. По поводу соглашений добавил бы глубину/формат (шаблоны) документирования. Иначе часто бывает, что крупная фича описывается в одном абзаце, а небольшой багфикс в ТЗ на несколько листов. Из своего опыта документирования часто натыкался на грабли, когда при обогащении бизнес-требований в функциональные (полу-ТЗ) получалась солянка, когда подобный документ бизнес уже не может согласовывать (ибо не понимает), а для разрабов становится в духе:
Как говорится, большая документация сама защищает себя от прочтения, не так ли?
Тут в общем нужно найти золотую середину исчерпывающей глубины, как для бизнеса, так и для аналитиков/разрабов/QA. Важный момент, к которому пришёл, нельзя разрывать отдельно бизнес и функциональные требования по разным документам, т.к. в ходе уточнения требований/тестов/апдейтов бизнес-требования безнадёжно устаревают.
Через разбор багов/инцидентов/проблем
А вот это украду, попробуем)
Документация гораздо лучше воспринимается, когда не просто текст а в картинках: диаграммы связей, workflows и прочие UML
Одновременно в таком формате она хуже поддается изменениям и совместной работе - ну не умеют разные Version Control с большинством форматов картинок работать. Соответственно, все эти картинки с большей вероятностью 'забудут' поправить, когда все уже поменялось.
+сюда же(особенно если задействовано несколько систем) BMPN или EPC (она лучше читается с обеих сторон баррикад). Ну и скриншоты/прототипы экранов.
Чем больше делает код, тем больше в нем связей, и происходит комбинаторный взрыв, так как сложность растет нелинейно.
Проблема в архитектуре приложения detected :) Сорян, но весьма вероятно, что дело в этом. И это не пофиксить докой в том смысле, что вы, в лучшем случае опишите тот mess, который у вас есть
Примерно так же, как разработчики считают писать комментарии к коду бесполезной затеей, ведь код должен быть понятен без них
На самом деле тут надо понимать, что любой сервис/метод/процедура - это white и black ящики. Первые - это то, что объект полезного делает, второй - как он это сделал. Первое намного важнее, так как вы понимаете зачем он нужен, что от него можно ожидать, вызывая из других объектов и т.д. Второе - уже явно не так важно на этом этапе, так как может быть использовано ТОЛЬКО во время внесения изменений. Иначе зачем туда лезть. Соответственно важно понять первое. Конечно, когда есть только код, который представляет собой "ХЗ" - тогда надо в в него лезть, чтобы понять логику.
Заниматься документированием реализации - ну такое, может и не пригодиться в принципе, а времени потратится много. Плюс - практика показывает, что mess при всей его неструктурированности обычно похож внутри, так как "говнокодинг" обычно в одном проекте подобен и поняв принцип на одном примере, остальные уже понимаешь читая по диагонали.
И опять же. Написанное в начале критично. Если у вас проблема со структурой кода - то в этой развилке надо в принципе понять, куда идти:
писать модули с нуля "правильно"
пытаться чинить что есть
еще есть вариант вообще "переписать", но это клиника
Просто подход номер один предполагает, что новое делается в рамках новой парадигмы, прилепляясь к старому, там где без этого никак. А вот подход два предполагает, что жить вы будете по старому с точки зрения кода, и со всеми проблемами которые в нем есть. И тут уже каждый решает сам, так как каждый проект имеет свои планы развития на будущее, объем "легаси", бюджеты и т.д.
Дальше не буду комментировать, так как есть принципиальное расхождение
Если проблема в коде, его структуре, каким-то техническим моментам (интеграция, безопасность, производительность ...) - дока их не решит, максимум опишет. Ну сорян, код лучше не станет работать, так как компилятор "комменты" игнорит. И решать надо ее, уже по ходу выставив требования к доке (хотя обычно джействительно хватает описания white-box)
Если проблемы в коде нет - тогда ее нет в принципе, потому что хорошо структурированный код "понимается" командой на раз-два. Есть проблема в аналитиках, ну так их можно "расстрелять, а лучше повесить, как в одном анекдоте". И набрать тех, которые помимо написания своей реальности начнут интересоваться структурой кода, спеками API, чтобы писать более приземленные документы
Фиксация требований - это хорошо на уровне тех, кто их пишет :) Им кажется, что они чего-то там "исправили". Вопрос в том, что коду на требования все равно. А тут все банально. Если вы пишете требования бизнесовые, то разработчику надо сесть и натянуть "сову на глобус", так как у него под рукой куча непонятного кода. Если же требования написаны от методов/процедур, то это по сути и есть white-box, или контракт сервиса (много разных названий). Но тогда, чтобы такое писать - должно быть понимание структуры кода и также эта структура должна быть
Если проблемы в коде нет - тогда ее нет в принципе, потому что хорошо структурированный код "понимается" командой на раз-два.
Понимается, понимается, но: "Слушай, а почему по пятницам 13-го в високосный год мы отказываем в обслуживании клиентам, у которых вторая буква фамилии - твердый знак?"
Код описывает - что и как делается. Но не описывает - почему и для чего это понадобилось.
Ну это вопрос уровня баго-фича и "перетрахивать" всю команду для решения такого вопроса явно лишнее. А если таких вопросов 100500 - тогда идем к структуре.
Возможно стоит подумать (я просто исходя из примера) о вынесении подобной логики в отдельный движок бизнес решений. После чего отдать его аналитикам и скинуть эту часть работы с разработчиков вообще :)
-------------
Тут сразу немеряно плюсов. Разработчики кодят backbone решения и все. Аналитики играются параметрами и правилами самостоятельно с заказчиками :)
вынесении подобной логики в отдельный движок бизнес решений.
Как будто то, что этот движок интерпертирует - не код. Будет тот же вопрос по схеме, нарисованной в этом движке.
Нет, не будет. Так как за прикладной код логики отвечает и пишет аналитик :) Ну или задает через таблички или иные формы для non-technical users. Разработчик только опишет для него модель доступных объектов для описания логики и все.
Дальше спрашивай сам себя :)
В итоге прилетает бага, у клиента в пятницу оторвало жопу.
Скидывают программистам, они ваще не в курсе, потому что это анадитики. Или программисты. Или всё таки аналитики.
А потом программист пишет письмо аналитику: слушай, мы тут всём отделом мозг ломаем уже в месяц. Теоретически это возможно если пятница 13. А аналитик говорит, ну ок, отключим 13. Наверно.
Я не совсем понимаю суть вашего поста
Ведь довольно таки очевидно, что если бизнес логика "отрывать жопу" или "оставить на месте" прописана в правилах - то очевидно, кто виноватик?
Даже безотносительно наличия такого компонента задача локализации места ошибки успешно решается тысячами команд по всему миру, в случае коректной декомпозиции приложения на "слабо связанные" модули
------------------
В реальности, т.е. по опыту реальных внедрений, обычно такого рода проблемы решает поддержка, так как всем понятно, что за логика и где она прописана. Т.е. проблема и место ее возникновения настолько очевидны, что ее локализация и решения могут вполне остаться на первой линии поддержки.
Плюс обычно не составляет сложности за Х минут прогнать банальный unit тест с входящими условиями в продуктива и увидеть "момент отрыва жопы" у себя на тесте
-----------------
К примеру, из смешного. Заказчик (в смысле банк) у себя в интернет банкинге поставил курс, который позволял своим клиентам наваривать "тугрики" банально покупая-продавая. Отследили по проводкам, дальше к нам "как вы такое могли написать и все такое"?
В ответ был составлен банальный SQL запрос по истории курсов и клиенту было точно указано место, время и ФИО того, кто выставил чудо настройки.
Вопрос был закрыт, реально перепутали местами "ячейки" :)
Понятно, там была просто табличка с аудитом, но сути это не меняет. Логика вынесена отдельно и отлично себя чувствует.
В реальности, т.е. по опыту реальных внедрений, обычно такого рода проблемы решает поддержка, так как всем понятно, что за логика и где она прописана.
Тезис в том, что в какой-то момент, несмотря на то, что известно где все это вписано - станет неизвестно, зачем оно туда вписано.
Это обход какого-то бага сторонней системы, который уже не актуален? Это обход какого-то бага у нас, которого уже нет? Это требование какого-то древнего закона/требования регулятора?
Потому что аналитик, который в первый раз это сформулировал - взял это из головы человека, которого потом на написанную систему заменили. И теперь, по прошествии лет так 8-15, уже никто не помнит и не может найти концов, почему и для чего такая бизнес логика тут стоит и что произойдет, если ее изменить или выкинуть.
А документацию, которая это объясняет, в свое время не написали.
Коллеги, тут просто два подхода. Кто-то предпочитает описывать баржак, кто-то - его трансформировать :)
Каждому свое :)
Прежде чем трансформировать надо бы описать.
Чтобы отслеживать, что по дороге при трансформациях ничего из нужного и полезного не утерял.
Ну это такое
Обычно, если вкладываются в трансформацию, то важнее описывать не as-is, а to-be. Все таки платить много денег чисто чтобы закрыть тех. долг не очень разумно и такой "проект" сложно защитить. А если к трансформации допиливать фичи, менять hardcode на конфигурабельность, то получить деньги на такую задачу намного проще. Плюс часто получается, что многие требования, как и код под них уже не актуален, так как поменялся бизнес контекст.
Про утерять ... есть такой очень усредненный показатель, что около половины фич вообще на фиг не нужны и никто ими не пользуется :) Как говорят, если во время переезда находятся вещи, к которым не прикасались пару лет - их смело можно нести на мусорку либо барахолку. Так и с функциями :)
Про утерять ... есть такой очень усредненный показатель, что около половины фич вообще на фиг не нужны и никто ими не пользуется :)
Так ими пользуются. Их софт выполняет. Но в особо экстремальных случаях люди вообще даже забыть могут, что софт это делает - работает и работает. А потом 'ненужный' код выкидывается и интеграция с чем-нибудь ломается.
Проблема в том, что если нигде не написано, для чего этот код стоит - то и понять, что оно сломается (или уже нет? Внешняя систему меняли же уже?) - нельзя.
Если у тебя в работе огромный легаси проект без понятной и структурированной документации, имеющий немалое количество интеграций и переживающий процедуру рефакторинга или простиктулху импортозамещения - тут одну только документацию писать можно годами, а ещё и работать над этим чудовищем надо успевать. А т.к. бизнес толковых техписов нанимать или выращивать не торопится - то это прям БОЛЬ.
Чем больше делает код, тем больше в нем связей, и происходит комбинаторный взрыв
Число связей растёт квадратично, а комбинаторный взрыв — это экспоненциальный рост.
Комбинаторный взрыв сложности кода с документацией конечно никак не связан, лечится это, как тут уже отмечали, с помощью Clean Architecture по большому счету, или подобными подходами, когда вы запрещаете не связанным друг с другом модулям иметь потенциальное влияние друг на друга. На более низком уровне Clean Code и в целом аджайл-подходы (TDD, самодокументирующийся код и вот это все) призваны бороться именно с этой проблемой. И это более действенный вариант с точки зрения именно роста сложности кода и снижения velocity и time-to-market, чем тщательное документирование - скажу как представитель проекта, где с внутренней технической документацией все довольно неплохо. Документация важна, но с комбинаторным взрывом сложности она как таковая и не борется.
А можно просто взять и поменять безалаберных проджектов на профессиональных, и тогда они сами со всем разберутся в проектах :)
Я вот тоже не понял, как документация решит проблему сложного кода.
Ну будут у тебя тонны документации, пусть даже идеальной, всё равно её читать взрывать мозг надо.
Почему ваш проект тонет или как начать фиксировать требования, когда у вас ничего нет