Заказчик требует документировать ПО.

В любом случае это не проблема программистов.

Настолько не проблема, что даже на ЛОР за советом прибежал. Ну да, ну да.

Что это за архитектура такая, интересно, что ее на маркерной доске ни разу не нарисовали и не сфотографировали?

Выскажу непопулярное мнение, что за такое надо линейкой по пальцам бить %)

все сроки разработки увеличиваются на 50-100%

С чего бы?

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

Мне тоже не нравится. Уйдет человек, который понимает, - платформа станет черным ящиком.

У многих бытует мнение, что лучшая документация - это код. У нас так и живут

Выскажу непопулярное мнение, что за такое надо линейкой по пальцам бить

Давайте я вас помирю. Код — это не документация, а документация — это не код. Код — это истина в последней инстанции, куда идут, чтобы на 100% быть уверенным, что софтина работает так, как работает. Но для взгляда с высоты птичьего полета код не подходит — именно для этого нужны доки. Ну и плюс еще нужны комментарии в самом коде для неочевидных вещей.

Выскажу непопулярное мнение, что за такое надо линейкой по пальцам бить %)

Или молотком. :)

Мне тоже не нравится. Уйдет человек, который понимает, - платформа станет черным ящиком

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

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

Uml-диаграмма пишется в plantuml за несколько минут. И заодно показывает насколько упоротое решение получилось, особенно если она начинает походить на ктулху утром с похмелья. Другие доки прекрасно генерятся по комментам если эти самые комменты нормально объясняют что происходит, и если каждый метод делает только одну вещь, а не 100500 разных дел с пачкой булевых флагов на входе

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

как это должно опровергнуть примеры в которых доку писать не нужно?

Которых не было?

Любая миграция данных в рамках рефакторинга старой структуры

Ты просто блюешь алфавитом

Где пруфы Джимми? Дай конкретный пример. Что мне с этим абстрактным высером делать? То, как я себе представляю разовый сценарий миграции в рамках своей инфраструктуры, не входит в проект вообще, это разовый код на выброс, к которому мы не вернёмся. И всё равно, это должно быть описано и отработано на тестовом стенде во избежание проблем. А если это раскатано у множества клиентов, то мы к этому сценарию не раз вернёмся, то ещё более очевидно, что это должно быть описано, иначе косяки будут неизбежно.

И на интерфейс тоже?

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

И фронт к бэку ещё не приходил с вилами? Крепкие у них нервы

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

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

Которых не было?

А про джобку это что?

Что мне с этим абстрактным высером делать?

Научиться думать абстракциями а не догматичными правилами.

У многих бытует мнение, что лучшая документация - это код. У нас так и живут.

Тут двоякая ситуация.

На уровне функций и классов - если код нормально написан - никакой отдельной документации не нужно. И так всё должно быть понятно из названий в коде.

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

Это одни и те же люди. У нас не настолько большой проект, чтобы делить на части. :)

не входит в проект вообще, это разовый код на выброс

Да, это разовый код на выброс, почему это не может быть частью проекта? Потому что тогда твое правило про то, что нужно писать доку превращается в тыкву? А может проблема в самом правиле?

Входящая документация в виде заданий на разработку и проектирование и тестирование итога на соответсвие.

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

Из чего я делаю очевидный вывод о рисках

Что ты тут не понял?

А про джобку это что?

У тебя какая-то абстрактная джобка, не понятно с чего бы она не должна быть описана

А тут ты что не понял?

Научиться думать абстракциями а не догматичными правилами

То есть, примеров у тебя вообще нет.

почему ты не ходишь все время с зонтиком?

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

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

Едва ли заказчик хочет, чтобы ему код продублировали текстом и картинками. Сам же говоришь - в 2021 это никому не нужно. А цена нормального архитектурного документа гораздо-гораздо ниже, чем 50% разработки.

Да, это разовый код на выброс, почему это не может быть частью проекта?

Потому, что ты его выбросишь, лалка.

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

Мой пример с миграцией данных для рефакторинга вполне конкретен, ты просто отказываешься воспринимать его. шлангуешь короче.

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

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

Потому, что ты его выбросишь, лалка.

Любой код из проекта рано или поздно выкинут. И че?)

Или молотком. :)

Сразу по лицу

Философию можно сколько угодно разводить, но всё равно всё сведётся к «поторгуйся с заказчиком». То есть, в интересах команды выжать с него максимум доплаты, в интересах заказчика - вообще ничего не доплачивать. Ещё, возможно, есть некая пороговая цена, ниже которой команда посчитает весь контракт убыточным и предпочтёт его разорвать, но заказчику её сообщать ни в коем случае не надо (он тогда заплатит ровно её и не больше).

Твой пример — говно без конкретики, тут воспринимать в принципе нечего. Если ты опишешь о каких конкретно миграциях речь, тогда будет что обсудить.

Твой пример — говно без конкретики, тут воспринимать в принципе нечего. Если ты опишешь о каких конкретно миграциях речь, тогда будет что обсудить.

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

Чего тебе не хватает в этом примере?

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

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

Едва ли заказчик хочет, чтобы ему код продублировали текстом и картинками. Сам же говоришь - в 2021 это никому не нужно. А цена нормального архитектурного документа гораздо-гораздо ниже, чем 50% разработки

Ну это всё, что я понял из фразы

И вот у одного заказчика пришёл новый техлид, который стал требовать документировать ПО. Вплоть до блок-схем алгоритмов. Требует описывать архитектуру словами и картинками.

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

Уже даже ядро линукса на раст переписывают потихоньку, не тупи, весь код временный.

До этого сообщения не было никакого примера, было только очень широкое понятие «миграция».

Ну, и? Есть у тебя набор альтеров для бд, и чо? Напиши в документации, что они есть и где их искать. Это не код на выброс, они применяются на каждом инстансе, а в зависимости от логики, могут наказываться и при развёртывании БД нуля.

Ты считаешь, что я за то, чтобы словами описывать альтеры?

Давайте я вас помирю. Код — это не документация, а документация — это не код. Код — это истина в последней инстанции, куда идут, чтобы на 100% быть уверенным, что софтина работает так, как работает. Но для взгляда с высоты птичьего полета код не подходит — именно для этого нужны доки. Ну и плюс еще нужны комментарии в самом коде для неочевидных вещей.

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

Заказчик приходит к разработчику и задает ему вопрос - а как у тебя работает вот такая-то фишечка? И разработчик ему не может ответить, потому, что реализация была написана фиг знает когда, писали её пять разных человек, каждый со своим видением. В результате - никто не знает, как работает решение.

Uml-диаграмма пишется в plantuml за несколько минут. И заодно показывает насколько упоротое решение получилось, особенно если она начинает походить на ктулху утром с похмелья

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

Код без документации - мусор, обладание которым приносит больше проблем, чем он даёт отдачи.

Хотел было согласиться, но… Учитывая, что ПО как явление появилось для того, чтобы можно было делать каку быстрее и проще, все правильно чуваки делают. Разработать ПО - это как сходить в туалет, результат схожего характера. Пилится одной командой, или вообще в одно рыло. Развалилась команда - нанимается галерный раб, чтобы копаться в легаси фекалиях, пока либо он не умирает от миазмов, либо фирма не отдает концы.

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

Заказчик приходит к разработчику и задает ему вопрос - а как у тебя работает вот такая-то фишечка

Вариант ещё больнее - аудитор по каком-нибудь iso27001 приходит к заказчику

Ну, и? Есть у тебя набор альтеров для бд, и чо? Напиши в документации, что они есть и где их искать.

каких альтеров? альтер тейбл? я про данные. И кто будет читать эту документацию?

Это не код на выброс, они применяются на каждом инстансе

да, один раз, а потом выбрасывается.

а в зависимости от логики, могут наказываться и при развёртывании БД нуля.

или нет.

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

Зависит от содержания и уровня детализации. Естественно делать одну диаграмму на все это пипос. А если «одна ручка одна схеиа», плюс отсылки на что-то общее типа «проверяем password policy, см #сцылк» - все норм

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

Ах если бы, если бы я в жизни не видел легаси это было бы чудесно.

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

весь код временный

Помнишь как пиндосы искали кобол-дедушку когда у них соцстрах развалился в прошлом году? Временный - понятие относительное.

У ведьмака был тезис о том что временный код не является частью проекта.

я про данные

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

И кто будет читать эту документацию?

Каждый новый человек, который будет вливаться в проект.

да, один раз, а потом выбрасывается

Тогда это не часть проекта. Ты её выбросил, понимаешь? Её в проекте больше нет.

сколько код должен жить в проекте что бы ты считал его частью проекта

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

Не временный, а одноразовый.

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

Я его уже дал Заказчик требует документировать ПО. (комментарий)

там написано «данных много». что тебе еще нужно?

Каждый новый человек, который будет вливаться в проект.

Зачем ему читать доку на код который выкинул?

Тогда это не часть проекта. Ты её выбросил, понимаешь? Её в проекте больше нет.

А до выброса это часть проекта?

Не временный, а одноразовый.

А если его 2 раза нужно запустить?))

Это он не прав. Можно открыть почитать тот же isms - на любой, даже самый засратый, скрипт должен быть хотя бы тикет если этот скрипт трогает продакшн.

Что твоему заказчику с твоего внутреннего тикета? А новой команде, которая через пару лет будет этот проект принимать после того, как ваша контора обанкротится, вы разбередётесь и будете сбиты автобусом?

Не я не прав, а он врёт.

вот, тикет или таска, но не полноценная же дока.

Если запустишь два раза, обязательно упомяни его в документации.

кто ее будет читать?