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

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

У заказчика аргумент, дескать код без документации - это программа на один раз. Типа поддерживать нереально. И соответственно они зависят от нас.

У вас проект открытый? Если да, пусть форкают, если нет - платят. Обнаглели просто.

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

Как на счёт генераторов документации? К примеру - Doxygen. Либо пусть платят намного больше за дополнительную работу и тут уже выбор будет между их деньгами и вашими нервами.

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

this

Ну требование логичное, исполнители меняются, а доки остаются. Но на доки всегда выделяют время/деньги, иначе это считается бонусом и требовать нечего. Послать всегда можно по ТК РФ.

Скорее всего заказчик хочет самостоятельно ПО разрабатывать дальше. Но для этого нужно понимать как что устроено.

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

код без документации - это программа на один раз. Типа поддерживать нереально

И он, в общем-то, прав. Но попытаться договориться о дополнительной оплате (и сроках) это не мешает %)

Обговаривайте дополнительную документацию на код до заказа отдельным пунктом за отдельную плату.

А если вам лень это делать - не нойте

++

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

Если нет, то пусть оформляют доп. соглашение, а уж от чего у вас эти условия зависят не знаю. То 5сть решать этот вопрос ваш руководитель должен.

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

Что касается комментариев в коде. Они тоже должны быть правильно оформлены. Комментарий в стиле char a;/*объявление переменной a*/ - коментарием не является. Из комментариев коде должен вырисоваться алгоритм и структура программы. Если он не вырисовывается - комментариев нет.

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

Вы неправы. Во всяком случае мой опыт подсказывает, что не правы.

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

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

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

Два ча… Нет, Три чая этому господину

+1

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

Ирод, как его земля только носит.

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

Я не знаю что у вас там творится, но поддержку заказчика. Дока на архитектуру и используемые алгоритмы нужна. Для этого обычно используют wiki где записываются все знания которые нужно передавать новым сотрудникам (не только по коду но и по инфраструктуре, и по настройки environment для работы). Там же на wiki помещаются ТЗ и хранится история изменений.
Я даже не знаю как без wiki работать над большим проектом. Вот допустим вам поступили требования на новую функциональность и тогда вы создаете wiki страницу с описанием того что нужно сделать, плюс все бизнес правила который должны быть реализованы в коде, если требования меняются вы там фиксируете изменения и согласования. Когда все будет реализовано наверное там стоит указать на ключевые места в написанном коде.

А вот в коде дока не нужна, конечно если это не дока над стабильным API, чего почти не бывает на живом проекте, разумеется это не касается передаваемых третьим лицам библиотек, фреймворков или публичных api. Если «контракт»(aka правила) не меняются, или даже правила выше по приоритету чем конкретная имплементация то тогда дока обязательно нужна в коде, где эти правила зафиксированы.

Каков наглец! Известно же, что код лучшая документация!

Грамотный заказчик попался, одобряю.

Какая разница где описывать архитектуру и «блок-схемы» в doxygen и аналогах или в ворде? В любом случае это делать надо. В doxygen конечно лучше, так как все вместе с кодом будет лежать в одном месте.

как его правильно послать

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

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

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

Требует описывать архитектуру словами и картинками.

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

Без документации код придется реверсинженирить.

Реверинженеринг это не про код тащето.

Но чуть сложнее проекты без документации - боль.

Смотря что считать документацией и смотря какое отношение вы имеете к проекту. В топике речь про отношение заказчик-исполнитель. То есть подразумевается, что заказчик как минимум в курсе что делает код. Мне не раз и не два доставался чужой код для которого я был в той или иной мере «заказчиком». Отсутствие документации ниразу не мешало править баги и добавлять новые.

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

Ну если это не writeonly то документацию так или иначе все пишут. Другой вопрос, может ли кто-то ещё понять что хотел сказать афтар. :)

Реверинженеринг это не про код тащето.

«Тащемто» это процесс не только ковыряния байт-кода

Цитирую: Reverse engineering (also known as backwards engineering or back engineering) is a process or method through the application of which one attempts to understand through deductive reasoning how a device, process, system, or piece of software accomplishes a task with very little (if any) insight into exactly how it does so.

Как думаете это должно быть юридически сформулировано в договоре?

Читать договор. ПО без документации суть вендор лок

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

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

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

На его месте я бы послал тебя и ушел к твоему конкуренту. Сдохнешь с голоду — передумаешь :)

Нет, конечно. Очевидные вещи в договоре не пишутся. Давайте ещё в договоре указывать, что код надо писать не ж#пой.

Читать договор и ТЗ. Если там про это сказано, то выполнять и соответственно быть по щам тем что такое подписал, не заложив оплату, если там этого нема - посылать нах.

Нормальное требование.

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

А вот это уже твои недоработки. Твоя задача тут объяснить ему, что это требует дополнительных трудозатрат, возможно, отдельного человека. Донести, что это точно такая же работа как написание кода.

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

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

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

У заказчика аргумент, дескать код без документации - это программа на один раз. Типа поддерживать нереально. И соответственно они зависят от нас.

Ну, ценник вдвое и вперёд.

И соответственно они зависят от нас.

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

У заказчика аргумент, дескать код без документации - это программа на один раз. Типа поддерживать нереально. И соответственно они зависят от нас.

Ну это твои проблемы?! Это естественно, так же и естественно, что полная документация поднимает прайс в два раза. Если это не было оговорено в контракте делайте доп соглашение и пошел он нахер со своими аргументами

Ололо, прожжённым индусам предъявили базовое и очевидное требование — писать документацию, они решили, что заказчик неадекват. Феерично.

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

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

И ты почему-то с этим не согласен?

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

Ты, видимо, никакого отношения к разработке не имеешь? Не вижу иного объяснения дуростям, что ты пишешь.

Писать документацию должны тех. писы, а не программисты.

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

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

ты что под документацией понимаешь?

Только не «общем-то», а «безусловно».

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

Я, зная как тяжело всё это делается, брал бы столько же как и за написание кода.

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

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

Нет. Они покупают разработку на заказ - это либо fix price, либо time&material. Во втором слечае проблем нет - нужны работы их оплачивают, а по fix price всё должно быть в договоре и в тз либо модные ныне чтз. Если там нету, то оплачивается отдельно. В любом случае это не проблема программистов.

А можно как-то посмотреть пример такой документации кода? Прям буквально каждую функцию описывать нужно?