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

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

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

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

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

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

Тред серьёзный, даже ленин включил адекватна.

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

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

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

согласен

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

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

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

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

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

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

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

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

молодец, до тебя что то начинает доходить.

Про себя забыл предупредить.

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

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

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

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

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

Это мой изначальный тезис. Ты Тупак развёл на разном месте.

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

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

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

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

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

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

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

Это мой изначальный тезис. Ты Тупак развёл на разном месте.

Красиво переобулся.

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

Организаций с многомилиардными оборотами, в которых я работал.

Тебя от количества опыта по швам не рвет?

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

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

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

Вася, ты охренел и заврался.

Недокументированные код — это в большинстве случаев дорогой в поддержке мусор

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

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

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

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

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

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

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

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

Нет, не начал. Более того, я тебе что раз уже упомянул закон Парето и рациональный минимум.

Ты что сразу так жестоко?

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

считать что документация нужна ВСЕГДА - это крайность.

Я же описал сценарий, когда оне не нужна. Ты надоел. Тренируй память.

хорошо, я думаю мы поняли друг друга

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

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

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

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

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

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

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

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

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

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

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

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

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