LINUX.ORG.RU
ФорумTalks

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

 


2

1

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

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

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

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

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

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

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

tootsoon ()

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

anc ★★★★★ ()

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

NAY_GIGGER ()
Ответ на: комментарий от anc

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

this

intelfx ★★★★★ ()

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

Lordwind ★★★★★ ()

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

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

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

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

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

Nervous ★★★★★ ()
Последнее исправление: Nervous (всего исправлений: 1)

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

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

zgen ★★★★★ ()

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

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

grem ★★★★★ ()
Последнее исправление: grem (всего исправлений: 1)

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

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

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

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

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

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

anc ★★★★★ ()

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

Nervous ★★★★★ ()
Последнее исправление: Nervous (всего исправлений: 1)

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

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

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

ergo ★★ ()

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

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

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

CaveRat ★★ ()

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

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

Aber ★★★★★ ()
Последнее исправление: Aber (всего исправлений: 1)

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

Harald ★★★★★ ()

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

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

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

Reset ★★★★★ ()

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Цитирую: 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.

ergo ★★ ()

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

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

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

olegsov ()
Последнее исправление: olegsov (всего исправлений: 5)

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

AP ★★★★★ ()

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

vtVitus ★★★★★ ()

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

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

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

urxvt ★★★★★ ()

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

AntonyRF ★★★ ()

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

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

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

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

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

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

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

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

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

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

AntonyRF ★★★ ()

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

AP ★★★★★ ()

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

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

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

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

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

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