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

Я представляю ситуации, когда такой код нужен. Я в таких ситуациях оказываться (больше) не хочу. А ты?

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

Я представляю ситуации, когда такой код нужен. Я в таких ситуациях оказываться (больше) не хочу. А ты?

А я не вижу в этом никаких проблем, в моих ситуациях все было норм.

и в особых случаях получить по лицу)

именно поэтому Бог создал удалёнку, чтобы девелоперы по лицу не получали )

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

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

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

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

Пример: Байки из склепа (комментарий)

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

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

Твоя проблема в том что ты придумал себе правило «нужно писать доку», а теперь столкнулся с исключением и не знаешь что делать. Так вот, любые правила - говно. Нужно всегда понимать зачем конкретно ты что то делаешь.

кустарщины

Как раз искал подходящее слово, но не нашёл.

Если является, то должна быть описана.

Нет, не должна, это будет работой в стол. Зачем писать доку которую ни кто не будет читать? Нравится работать в стол?

В чём проблема, написать «есть такая джоба, нужна она для того-то»?

Ты топишь за ничем не обоснованное раздолбайство.

Зачем писать доку которую ни кто не будет читать?

Если не будут, то ССЗБ. Но если она понадобится, а её не окажется, то мудаком в этой ситуации являться будет тот, кто поленился написать пару предложений.

Я же тебе скинул ссылку на реальный пример из жизни, прочти.

Если не будут, то ССЗБ. Но если она понадобится, а её не окажется, то мудаком в этой ситуации являться будет тот, кто поленился написать пару предложений.

Все верно. Это оценка рисков. Так вот оценивать нужно как профит/затраты и это оценка не обязана быть >1

Я даже не знаю как без wiki работать над большим проектом.

Вот выросло...

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

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

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

Я же тебе скинул ссылку на реальный пример из жизни, прочти.

И в чем мораль? У вас была написана документация? Если да то судя по всему она не помогла? Какие выводы то?

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

Не в коде, а в вики.

Какие выводы то?

Если бы прочитал внимательно, сам бы их сделал. Проблема была не на нашей стороне. У них не было документации и они не знали, что используют наше старое API.

Мораль: пиши документацию, или сядешь в лужу.

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

Какой правильный чувак.

Вплоть до блок-схем алгоритмов.

УБИТЬ ЭТУ СКОТИНУ!

В комментариях к задаче в трекере? Оно потеряется.

Не в коде, а в вики.

А если в коде удобнее? Почему в вики?

Если бы прочитал внимательно, сам бы их сделал. Проблема была не на нашей стороне. У них не было документации и они не знали, что используют наше старое API.

А с чего ты решил что не было? Может была, но бесполезная, написанная такими же бюрократами как ты. Или была нормальной но про нее даже не вспомнили?

Мораль: пиши документацию, или сядешь в лужу.

деды писали и ты пиши, думать не нужно.

В комментариях к задаче в трекере? Оно потеряется.

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

Еще в гите можно в коммитах оформлять ссылки на таски, это документация?

А с чего ты решил что не было?

С того что на официальный запрос, так же повторённый несколько раз неформально, был ответ, что нет, не используется. И с того, что реально не было.

про нее даже не вспомнили?

Такие же раздолбаи как ты?

Давай теперь на каждый сих вычитывать 100% кода в поисках документации. Капец у вас порядки в Индии.

Особенно если код отдали во вне, и доступа к вашему трекеры нет.

С того что на официальный запрос, так же повторённый несколько раз неформально, был ответ, что нет, не используется. И с того, что реально не было.

А почему ты думаешь что если бы была это помогло?

Давай теперь на каждый сих вычитывать 100% кода в поисках документации. Капец у вас порядки в Индии.

Какие 100% кода?) Ты видишь непонятный тебе код, открываешь и видишь там все, что нужно. зачем заставлять людей лезть в вики? потому что деды так делали?

Нет, нет и нет.

Почему?

Ты все время пишешь «как нужно» но сам же не можешь объяснить зачем и кому это нужно)) Это звоночек.

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

Всё просто: заказчику объясняется, что все сроки разработки увеличиваются на 50-100%, при чем, за эту всю радость он будет платить из своего кармана. Если его устраивает — пишешь блок-схемы алгоритмов. Конечно, если это устраивает и тебя тоже. Ну типа лично я не против того, чтобы описывать свою архитектуру словами, но обычно это нахер никому не нужно и люди платят только за работающий код. Обычно когда заказчик узнает, насколько дороже ему обойдется такая разработка, то все басни про «одноразовый код без доков» отходят на второй план.

Вообще, у меня иногда складывается такое впечатление, что распределение по должностям в IT строится таким образом:
 — Писать код умеешь? Будешь разработчиком.
 — Не умеешь писать код? А читал документацию по фреймворку? Будешь техлидом.
 — Не умеешь писать код и не читал доков? Будеш Agile коучем.

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

Ну, то есть, логика: ты — идиот, не хочешь писать, а значит все тоже идиоты, не захотят читать. Железно.

Это бы помогло просто потому, что есть определённая ответственность за косяки.

Вот +1 просто.

Но есть еще вопрос - а как у заказчика обстоят дела с требованиями к ПО?

Ну, то есть, логика: ты — идиот, не хочешь писать, а значит все тоже идиоты, не захотят читать. Железно.

Ты сам это придумал, я такого не говорил.

Какой в жопу непонятный код? Тупая шлангота пошла. Я тебе ситуацию выше дал.

Какой в жопу непонятный код? Тупая шлангота пошла. Я тебе ситуацию выше дал.

И я тебе выше точно так же дал ситуацию с разовой джобкой.

Ты меня не спрашивал.

Тебе нужно задеплоить сервис, ему нужна кафка, мнрга и ещё туча всего, он нетривиально конфигурируется с помощью DSL. Документации нет, читай код, удачи тебе.

Уверен что индукция тут применима?

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

С чего бы?

Никакой заказчик в своем уме не откажется от исполнителя с кучей рабочего кода да еще и без документации.

Ещё как откажется.

Нормальных примеров у тебя всё равно не было, конкретику ты разбирать отказываешься. У тебя какая-то абстрактная джобка, не понятно с чего бы она не должна быть описана.

И врёшь, обоснование я тебе уже давно дал: работа с рисками. Сегодня ты не знаешь, что понадобится тебе завтра.

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

такие требования бесят. как его правильно послать?

Написать псж и сменить работу. За код (и тем более какое «комплексное решение» с деплоем и прочим) без документации надо расстреливать. У меня есть один такой проект, старых разрабов хочется убить каждый день.

Возвращаясь к тому, почему бы это помогло. Я же со знанием говорю, а не просто так, с ребятами мы тесно работали как со своими, это не предположение. Они честно пытались удостовериться, что старое API не нужно, они просто не могли знать. Все клиенты они обновили, что могли из своего проверили.

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

но на практике ты этого не делаешь

на оплате это никак не сказывается.

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

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

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

Или ты про «сам не пишешь доку»? Пишу, особенно на интерфейсы и алгоритмы сложнее чем «переложить жсон в базу». Больше всех рад фронтенд, у них больше вообще вопросов не возникает

Как вы сдавали раньше проекты без документации - я не понимаю

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

Могучий индусской фольклор.

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

И на интерфейс тоже? Особенно на rest, gql/protobuf хоть какую-то спеку имеют.

Нормальных примеров у тебя всё равно не было, конкретику ты разбирать отказываешься. У тебя какая-то абстрактная джобка, не понятно с чего бы она не должна быть описана.

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

И врёшь, обоснование я тебе уже давно дал: работа с рисками.

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

Сегодня ты не знаешь, что понадобится тебе завтра.

Иди сделай себе пирсинг на члене, ты же не знаешь что тебе понадобится завтра.

документировать надо это конечно он прав.

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

Если документация нужно прямо красивое и в неких стандартах, то плюс новая штатная еденица и соотв.инфраструктура для ведения документации (да, одной wiki на команду не обойтись)

А в начальных условиях оплаты проекта сие не предусмотрено. Далее «Любой каприз за ваши деньги». Утром деньги, вечером стулья.