LINUX.ORG.RU
ФорумTalks

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

 


2

1

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

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

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

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

@tootsoon на всякий случай хочу тебя предупредить о том, что WitcherGeralt, lenin386 и AP мягко говоря троли с плохим характером, относись к их словам с большим скепсисом, особенно если они не подтверждены другими участниками форума или другие говорят похожее, но иначе, в этом случае приоритет за тем, что говорят другие.

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

Внешнему заказчику ничего, и именно затем ему и нужна дока, чтоб если не самому читать так хоть аудитору дать при случае

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

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

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

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

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

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

Чини либо память, либо дислексию.

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

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

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

А ещё он будет существовать пока ты его пишешь, а писать ты можешь его целую неделю. Не останавливайся в тупняке и шланговании.

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

И это мы еще не затронули роль семантики во всем этом и самого качества доки)))

Но ты как настоящий бюрократ смотришь не на проблемы которые нужно решать а на правила которые сам себе придумал и теперь катаешься по одним и тем же рельсам из нейронов.

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

А ещё он будет существовать пока ты его пишешь, а писать ты можешь его целую неделю. Не останавливайся в тупняке и шланговании.

но это ты тут доказываешь что дока нужна потому что она нужна.

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

Давай переформулирую, чтобы твой внутренний барашек перестал упираться.

Не нужно документировать тот код, который ты (компания) не намерен поддерживать. Это и есть код «на выброс».

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

А семантика в коде может влиять на сложность поддержки?

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

Правила выдумал не я, они родились исходя из практики.

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

и самого качества доки

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

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

Правила выдумал не я, они родились исходя из практики.

Из чьей практики?

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

Сказал мастер спорта по шлангованию

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

Польза документации это прогнозируемая велечина.

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

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

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

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

Ты описываешь крайний паталогический вариант. Причем, наличие документации от него не спасет, потому что никто не будет писать доку строка в строку. А индусам очень легко написать рекуррентно-мутабельно-гоутушную лапшу, которая на графиках будет выглядеть прекрасно, но никто не будет понимать, как она работает. Более того — именно этот подход приводил к тому, что долгое время «индустрия» держалась за гоуту как за спасительную соломинку — на графиках-то оно выглядит хорошо.

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

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

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

WitcherGeralt ★★ ()

Как же раздражает эта избалованность разработчиков.

Типа я пишу код, не царское это дело писать к нему документацию.

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

Спрашивается кому ты сдался такой программист если ты ничего не умеешь кроме печатания кода?

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

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

Ты начал спорить с тем что этот минимум может быть 0.

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

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

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

Типа я пишу код, не царское это дело писать к нему документацию.

Архитектурную документацию должен писать архитектор, а не кодер. Это разные роли, разная квалификация, и как следствие - разное видение/понимание проекта.

Спрашивается кому ты сдался такой программист если ты ничего не умеешь кроме печатания кода?

Открой любой сайт с вакансиями, там написано, кому он сдался.

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

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

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

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

Всё правильно делает.

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

Перечитывать договор очевидно

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

Ты описываешь крайний паталогический вариант

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

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

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

Спрашивается кому ты сдался такой программист если ты ничего не умеешь кроме печатания кода?

Все зависит от размера компании. У нас бэкенд делает деплой, а офис-менеджер недавно настраивала политики безопасности для рабочих ноутов. Компания мелкая, все делают всё что могут.

А в крупной конторе код-мартышка обычное дело, когда над ней стоит рукгруппы, отдела, архитекторы, техписы и три дюжины манагеров

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

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

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

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

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

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

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

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

Ты начал спорить с тем что этот минимум может быть 0

Примениельно к тому, на чём я настаивал, и не может.

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

Повторяю в третий раз:

Программа минимум: интерфейсы, данные, назначение каждого компонента в проекте

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

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

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

Поддерживаю.

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

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

А если ты осилишь прочитать то что я написал то сможешь найти там вот такую фразу

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

В общем мы тут на самом деле не спорим а описываем две крайности.

Все что ты говоришь верно но не в 100% случаев вот и все.

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

Программа минимум и Закон Парето — это не крайность. Разупоритесь, сир.

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

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

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

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

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

Будет очень забавно (нет), если единственным способом понять, что она делает, будет запустить ее и посмотреть, что получится.

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

ведь ты двух слов связать не можешь

Наверное, здесь и кроется причина нелюбви к писанию документации %)

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

Будет очень забавно (нет), если единственным способом понять, что она делает, будет запустить ее и посмотреть, что получится.

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

Данных для поддержки более чем достаточно. Нету никаких проблем о которых стоило бы беспокоиться.

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

ктулху утром с похмелья

Попытался представить, неполучилось :)

с пачкой булевых флагов на входе

Это ещё хороший, даже очень хороший функций. Самое вкусное, что я видел, это строка которая потом прогоняется через кучу if-ов, этакий забор из if else.

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

Единственная причина это нежелание работать в стол. Да когда я пишу доку я думаю о том что ее кто то будет читать и рекомендую всем так делать.

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