LINUX.ORG.RU
ФорумTalks

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

 


2

1

Привет, комрады.

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

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

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

Ответ на: комментарий от vtVitus

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

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

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

AP ★★★★★ ()
Ответ на: комментарий от Manhunt

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

С чего бы?

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

byko3y ★★★★ ()
Ответ на: комментарий от CaveRat

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

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

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

byko3y ★★★★ ()
Ответ на: комментарий от another

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

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

byko3y ★★★★ ()
Ответ на: комментарий от byko3y

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

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

upcFrost ★★★★★ ()
Ответ на: комментарий от TDrive

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

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

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

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

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

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

WitcherGeralt ★★ ()
Последнее исправление: WitcherGeralt (всего исправлений: 2)
Ответ на: комментарий от upcFrost

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

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

another ★★★★★ ()
Ответ на: комментарий от WitcherGeralt

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

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

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

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

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

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

TDrive ★★★★★ ()
Ответ на: комментарий от another

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

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

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

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

Manhunt ★★★★★ ()
Ответ на: комментарий от upcFrost

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

another ★★★★★ ()
Ответ на: комментарий от WitcherGeralt

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

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

TDrive ★★★★★ ()
Последнее исправление: TDrive (всего исправлений: 1)
Ответ на: комментарий от MKuznetsov

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

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

Manhunt ★★★★★ ()
Последнее исправление: Manhunt (всего исправлений: 1)
Ответ на: комментарий от TDrive

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

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

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

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

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

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

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

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

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

WitcherGeralt ★★ ()
Ответ на: комментарий от byko3y

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

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

Manhunt ★★★★★ ()
Ответ на: комментарий от TDrive

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

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

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

WitcherGeralt ★★ ()
Ответ на: комментарий от WitcherGeralt

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

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

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

TDrive ★★★★★ ()

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

firkax ★★ ()
Ответ на: комментарий от TDrive

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

WitcherGeralt ★★ ()
Ответ на: комментарий от WitcherGeralt

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

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

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

TDrive ★★★★★ ()
Ответ на: комментарий от TDrive

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

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

WitcherGeralt ★★ ()
Ответ на: комментарий от Manhunt

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

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

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

byko3y ★★★★ ()
Ответ на: комментарий от WitcherGeralt

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

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

TDrive ★★★★★ ()
Ответ на: комментарий от TDrive

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

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

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

WitcherGeralt ★★ ()
Ответ на: комментарий от byko3y

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

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

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

CaveRat ★★ ()
Ответ на: комментарий от upcFrost

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

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

byko3y ★★★★ ()
Ответ на: комментарий от lenin386

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

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

seiken ★★★★★ ()
Ответ на: комментарий от CaveRat

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

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

upcFrost ★★★★★ ()
Ответ на: комментарий от WitcherGeralt

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

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

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

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

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

или нет.

TDrive ★★★★★ ()
Ответ на: комментарий от byko3y

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

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

upcFrost ★★★★★ ()
Ответ на: комментарий от WitcherGeralt

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

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

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

TDrive ★★★★★ ()
Ответ на: комментарий от TDrive

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

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

upcFrost ★★★★★ ()
Ответ на: комментарий от TDrive

я про данные

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

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

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

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

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

WitcherGeralt ★★ ()
Ответ на: комментарий от TDrive

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

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

upcFrost ★★★★★ ()
Ответ на: комментарий от WitcherGeralt

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

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

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

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

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

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

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

TDrive ★★★★★ ()
Ответ на: комментарий от TDrive

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

upcFrost ★★★★★ ()
Ответ на: комментарий от upcFrost

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

WitcherGeralt ★★ ()
Последнее исправление: WitcherGeralt (всего исправлений: 2)
Закрыто добавление комментариев для недавно зарегистрированных пользователей (со score < 50)