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

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

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

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

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

это две разные документации

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Фейспалм.

Это великолепно, торжество бюрократии.

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

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

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

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

Чай и я люблю :)

А про документирование что скажете?

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

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

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

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

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

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

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

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

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

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

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

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

Что такое «вендор лок»?

А что сейчас используют вместо блок-схем? Буду использовать ваш ответ в дискусии с закачиком.

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

Это не стартап

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

Планирование на две недели - это Agile методология :-)

Нет.

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

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

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

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

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

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

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

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

Плюсую.

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

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

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

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

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

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

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

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

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

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

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

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

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

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