Шура Люберецкий

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

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

Примерно тут возникает еще одна проблема — «код и документация» нужны заказчику в удобоваримом для него виде. Скажем, «код валяется в разных местах на диске у Васи, документация — в виде обрывков бумажек в столе у Пети» ни одного заказчика не устроит; «исходники и Javadoc лежат на гитхабе там-то и там-то» — приемлемый вариант для «технарей»; «все документы по проекту находятся в CVS-системе фирмы, а также записаны на компакт-диски и находятся в двух разных помещениях архивов» — вариант повышенной энтерпрайзности, ну и так далее.

И тут мы приходим к одной поучительной истории — про ЕСПД. Идея 19 и 34 серии ГОСТов, если вдуматься — это решение проблемы, описанной в предыдущем абзаце. Если говорить на языке более современных подходов к разработке ПО — типа RUP или OpenUP — то они описывают «артефакты», которые должны возникнуть в ходе разработки программы или автоматизированной системы, и требования к содержанию и оформлению этих «артефактов», позволяя заказчику, разработчику и потребителю ПО говорить «на одном языке».

Проблем с ЕСПД две — откровенный саботаж всякого процесса документирования своего творчества со стороны программистов и (как позже увидим, непосредственно вытекающая из этого) устарелость стандартов. Но начнем мы все же с саботажа. Давайте попробуем «изготовить» полагающийся по ГОСТ 19.401-78 «Текст программы». Поймайте программиста и попросите у него «текст программы». Ответом вам будет либо набор файлов (хорошо, если он сопровождается каким-нибудь Makefile), либо, если вы используете много «чужого» кода — долгая дискуссия, где заканчивается ядро Linux и начинаются ваши доработки. Дальше вы смотрите на ГОСТовские требования и понимаете, что распечатка ядра Linux или какого-нибудь веб-фреймворка на бумаге — это, конечно, прикольно — но отдел технической документации у вас это не примет.

Дальше выясняется — со слов коллег, сдававших сделанную по ЕСПД документацию раньше — что архив и нормоконтроль удовлетворятся сделанным в Word документом, содержащим что-то, похожее на исходники программы. Не вопрос! — думаете вы, и лихим Ctrl+C — Ctrl+V набиваете вордовский шаблон неработающими исходниками. Собственно, где-то на этом этапе в 1937 году вас бы ждал расстрел за подлог документов и саботаж (кстати, вы никогда не задумывались, что сокращение ИТР обозначает одновременно инженерно-технических работников и иностранные технические разведки?) — но сейчас времена более вегетарианские. и за такое очковтирательство никому ничего не будет.

Маленькое отступление — если бы вы не слушали «более опытных» коллег, а пошли бы в архив с тортиком, то вы смогли бы выяснить, что записанный на компакт-диск zip-архив с исходниками тоже сойдет. Впрочем, особо красноречивые товарищи могут попробовать научить работающих в архиве девушек пользоваться TortoiseHg.

Примерно так же происходит подготовка любых других документов «по ГОСТ» — вместо минимально читаемого Javadoc «Руководство программиста» будет куцей компиляцией форменного бреда; «Руководство системного программиста» будет описывать все, кроме того, что действительно нужно. В конечном итоге на написание документации будет посажена «девочка», совершенно не задумывающаяся о сути производимой работы, но неплохо умеющая писать формально удовлетворяющую требованиям нормоконтроля документацию.

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

В принципе, с чем-то подобным столкнулись и обычные инженеры, конструктора и так далее — но в отличие от программистов, там довольно быстро осознали, что стоит привести ГОСТы в соответствие с реальностью XXI века — поэтому в ЕСКД где-то в начале 2010-х легализовали, к примеру, «электронный документ» (собственно, ГОСТ 2.051-2006 приняли еще раньше, как несложно догадаться — в 2006). Технически продвинутые программисты — наоборот, предпочитают оставаться в реалиях 1970-х годов по причине полной неспособности взаимодействовать с «нехорошими бюрократами». Остается их с этим поздравить.

PS Написано по мотивам личного опыта автора, your mileage may vary.