LINUX.ORG.RU
ФорумTalks

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

 


2

1

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

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

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

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

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

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

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

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

Самое вкусное, что я видел, это строка которая потом прогоняется через кучу if-ов, этакий забор из if else

Добавить трехэтажных регулярок, будет вообще заглядение.

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

Все это не является документацией напрямую

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

Или мы пришли к тому что и код это в общем то документацию?

В общем случае нет, ящетаю. Потому что по коду видно только то, что он делает, а не то, чего этим хотел добиться афтар. Намерения афтара есть только в его голове — и в документации.

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

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

Все так. И документация тоже разная на разный уровень. Опять же пример - политика паролей. Есть дока прям сверхвысокого уровня доя СЕО, где написано «пароли должны быть збс». Есть проектная дока где этот «збс» расписан сколько символов и каких. Есть дока на gql/rest для фронта, где кратко продублировано что есть збс и какой код ответа ожидать. Есть коммент в коде бэкенда. Есть тикеты на все это.

В совокупности все эти вещи и есть документация. Это не просто «стопка бумаги в ящике»

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

Ну вот описание начальной и конечной схемы данных это ТЗ.
Просто в таске написано что нужно сделать. Если речь о том что на любой код должна быть хотя бы таска с номером и это будет тем самым минимумом документации, то ок.

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

Самое вкусное, что я видел, это строка которая потом прогоняется через кучу if-ов, этакий забор из if else.

Строка тогда ещё должна в yaml переводиться, с табами и переносами строк каким-нибудь левым символом вместо \n. For the glory of Satan, так сказать

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

Западные мудрецы говорят, что для проекта обычно нужно около четырех видов документации

Это доки для эндюзверя, да и то деление из твоей статьи очень условное и высосано из пальца. Как правило, чем более сложна и непонятна система — тем больше для нее нужно документации. Ты вот давно читал документацию по пользованию дрелью? Или пультом дистанционного управления? Особенно последнее является ни разу не простым устройством, но, тем не менее, дети спокойно его осваивают без доков, как и интерфейс смартфона.

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

Ты вот давно читал документацию по пользованию дрелью? Или пультом дистанционного управления?

А в чем проблема? Пульт читал к смарт-лампочкам из икеи месяц назад, не прочитав ман их хрен подключишь

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

Самое вкусное, что я видел, это строка которая потом прогоняется через кучу if-ов, этакий забор из if else

Добавить трехэтажных регулярок, будет вообще заглядение.

«Творец» к счастью не в курсе существования регулярок. Но и пара, тройка сотен строк if-else ничуть не хуже.

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

На момент написания «шедевра» yaml был ещё в зачаточном состоянии. А вот насчет «левых» символов, этого добра как грязи было. Экономили такскзть на спичках. И это лежало в СУБД.
Ещё оттуда же вспомнилось. Куча глобальных переменных в том числе есть однобуквенные и иногда, ради разнообразия, в какой-нибудь функции внезапно может оказаться такая же(тоже название, тот же тип), но локальная.

anc ★★★★★
()

С одной стороны, документировать надо. С другой стороны, история знает, как выглядит ад, дорога в который вымощена такими благими намерениями. А именно: комментарии говорят одно, документация говорит другое, программа ведет себя по-третьему. Вся надежда на историю коммитов, а там описания типа «asdasdf more work».

Короче, все говно, кроме мочи, и все мы умрем к чертям собачьим.

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

Программисты долго добивались того, чтоб ТЗ было длиннее программы. Но теперь они добиваются того, чтоб договор был длиннее программы.

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

Байки из склепа.

С другой стороны, история знает, как выглядит ад, дорога в который вымощена такими благими намерениями

И так, есть требование: наличие javadoc в коде на каждом классе, натравлен статический анализатор который не позволит залить что-то без него, итог:

/**
 *  MyClass.
 */
class MyClass {
}

И так везде, по всем проектам, во всех командах, во всем коде написанном за последние ~5 лет. Зато какой-нибудь PM отчитался о внедрении лучших практик и записал в «достижения на прошлой работе» в своем резюме.
Организация настолько большая и бюрократическая что это никто не отменит, да и подумайте как это ужасно звучит - «отменил требования обязательного документирования в коде». Плюс во всех автоматических анализаторах кода процент документирования упадет.

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

Да он не про то спрашивал, а как послать с таким требованием)

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

в какой-нибудь функции внезапно может оказаться такая же(тоже название, тот же тип), но локальная.

В пистоне есть built-in метод id. Количество боли, которое приносит эта штука (вернее её имя) в кривых руках, не поддаётся никакому описанию

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

О длинных договорах всегда мечтали юристы, а не программисты.

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

Ты вот давно читал документацию по ... пользованию ... пультом дистанционного управления?

Час назад. :) Пульт управляет исключительно телеком.

но, тем не менее, дети спокойно его осваивают без доков,

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

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

Что это за архитектура такая, интересно, что ее на маркерной доске ни разу не нарисовали и не сфотографировали?

Архитектура для тебя это такие квадратики со стрелочками? Ну тогда вопрософ нема.

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

id хоть как-то осмыслен. А вот варианты типа Z, F, H которые к тому же структура и т.д., то есть в результате видим что-то типа if ( Z.H.K < S.Y.P от ахренительно информативно. Вот ещё оттуда же вспомнилось, хоть как-то разобравшись с этой одно-двух буквенностью и задокументировав, выяснилась ещё одна особенность - необязательность присвоения значений. Поясню, есть глобальная переменная Z которая на самом деле структура и вроде на первый и второй и третий взгляд все поля у неё заполняются валидными значениями. Но как выяснилось есть нюанс. Далее по коду среди вороха if-ов обнаруживается что-то типа Z.D.H=0. Такой хитрый подход, сначала присвоим валидное значение, а потом начнем выяснять надо ли оно нам было делать. И ладно бы это было везде так, можно было бы понять и простить смириться, ан нет видимо от настроения пейсателя в момент говнокодинга зависело.

anc ★★★★★
()

Либо у заказчика появился новый сотрудник управленческого уровня, который точно_знает_как_правильно, либо заказчика контролирует какая-либо суровая инстанция.

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

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

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

Так вот, документация к ПО помогает избавить заказчика от массы возможных ТЕХНИЧЕСКИХ проблем.

sparkie ★★★★★
()

О_о, а как вы вообще до этого деньги то зарабатывали?

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

Архитектура для тебя это такие квадратики со стрелочками?

Хорошо шлангуешь, убедительно!

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

Это доки для эндюзверя

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

деление из твоей статьи очень условное и высосано из пальца

Фейспалм.

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

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

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

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

То есть как в школе? Блок-схемы и прочее? Это же долго и скучно…

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

Интересный подход. А можете показать пример?

Свой или публичный.

tootsoon
() автор топика

Ну во-первых, как справедливо отметили выше,

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

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

Во-вторых, надо смотреть, что за заказчик. Если, например, требуется сертификация по требованиям либо ФСТЭК, либо Минобороны, то там без документирования послан будет не заказчик, а вы.

В третьих, объём документирования тоже может быть предметом торга. Может, тому техлиду будет достаточно, если вы нарисуете в нотации UML схемы классов и компонентов. Или сгенерируете описание Doxygen-ом, если комментарии в коде приспособлены к такому повороту событий.

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

Документации кода не нужна

Что это если не документация кода::

Если получает слишком много объектов/состояний то может понадобиться добавить диаграммы (диаграммы классов, последовательностей или marble diagram, etc).

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

показать схемой как все компоненты должны инициироваться и взаимодействовать

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

Ты так топишь за документирование. А можешь показать пример своей документации. В том объёме, котоырй ты считаешь разумным?

tootsoon
() автор топика

Добавь doxygen - IDE показывают как документацию, и при сборке в pdf/html сам рисует блок-схемы

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

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

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

Внутреннюю документацию коммерческих организаций? Ты здоров?

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

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

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

Тем временем, тут продолжают кричать, что комментарии и документация не нужны…

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

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

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

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

да, это будет честно. но решение должен принимать он.

Плюсую.

Zhbert ★★★★★
()

Тут многое зависит от того, на каком этапе находятся деньги. Если у заказчика, то лучше что-нибудь изобразить. Если уже у вас, то просто тыкаете в договор, что «не предусмотрено». Потом формируете дополнительный этап по формировании документации за отдельную плату. Сроки, результат и проч. Как за реальный труд. Как мне кажется, документация должна состоять из 2-х источников: спецификация и реализация. В их содержание даже не нужно очень даже сильно углубляться. В подробности какие-то. Главное очертить пределы, в которых документация имеет смысл. И уже потом, если у заказчика найдётся эхперд, который её осилит, то можете уточнять её следующим этапом со следующей оплатой. Т.е. фактически та же самая разработка. Только вместо слова «программа» будет стоять слово «документация».

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

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

ибо программисты обычно еще и писать грамотно не все могут

Тогда и о написании приличного кода речи нет.

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

Всегда радовала твоя категоричность и уверенность в собственной правоте.

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

А на чтение ее потом теми, кто ее не писал?

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

Тогда и о написании приличного кода речи нет.

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

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

Что это если не документация кода:

Если получает слишком много объектов/состояний то может понадобиться добавить диаграммы (диаграммы классов, последовательностей или marble diagram, etc).

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

показать схемой как все компоненты должны инициироваться и взаимодействовать

Документация кода - это ссаный doxygen. А то, о чем он говорит - это документация архитектуры. Загугли по словам «software architecture document».

Manhunt ★★★★★
()
Последнее исправление: Manhunt (всего исправлений: 1)
Вы не можете добавлять комментарии в эту тему. Тема перемещена в архив.