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

"Словарь IT-терминологии"

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

Программистов можно понять – если разработку подробно документировать, то это приведёт к ещё большему запутыванию и без того запутанного проекта.

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

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

Таким образом, после первого же аврала мы имеем расхождение документации и реального положения дел. Что уже само по себе может стать причиной следующего аврала – даже если над проектом работает всего-то один человек. Портрет программиста, чешущего репу на предмет "блин, и что же я хотел сказать этой вот функцией?" уже давно стал классикой. Ну а принцип "не убирай из проекта непонятный и явно ненужный код, потому что он может оказаться критически важным" давно стал признаком профессионализма.

Понятно, что речь идёт о технической, внутренней документации, предназначенной исключительно для разработчиков и проектировщиков. User's manual – это отдельная песня и здесь мы её петь не будем.

Получается, что документация в её классическом виде (см. эпиграф) есть не бесполезная трата времени, а скорее вредная трата времени. Вспомните, когда вы последний раз по-серьёзному документировали свои разработки и чем это закончилось.

Вопрос, как заставить программистов документировать код, поддерживать документацию в актуальном состоянии, и чтобы при этом проекту не наносился ущерб, только кажется сложным. Ответ прост, как мычание – документация должна быть частью кода. Выбрасываем код, выбрасывается и документация к нему. Добавляем – добавляется. Переписываем – нужно быть просто страшным лентяем, чтобы не переписать заодно и пару строчек комментария. А страшных лентяев немного, их можно выявлять и давить, пока маленькие.

Технический способ решения проблемы также давным-давно придуман. Посмотрите на Visual Studio .NET – M$ понадобилось всего-то семь версий среды разработки, чтобы додуматься до форматированных комментариев, которые служат основой для генерации документации к проекту. И, конечно, в M$ это сделали с шиком: XML-тэги, автоподстановки, эргономика. А вот в Perl такая система "документации-в-коде" (POD) существует уже лет сто, хоть и без шика, но вполне в рабочем виде.

К чему я веду этот длинный заморочный базар? К тому, что подобная концепция очень хорошо вписывается в работу с V7. Ситуации, когда над одной конфигурацией в разное время работают разные люди является прямо-таки стандартной. И не только у франчайзи. Кто, что и когда делал? Как связаны модули друг с другом? Для чего нужна та или иная глобальная функция? Чтобы ответить на этот вопрос, нужно читать код.. А код каждый кодер пишет по-своему. Если перенести на бумагу маты, сложенные одними кодерами на других в процессе разбора логики поведения модулей, то получится лист длиной с пару экваторов, если не больше.

А ведь документировать код не просто, а очень просто:

Вытащить из MD все "документальные" куски и построить на их основе структурированное описание конфигурации – это уже дело техники, можно, скажем, взять Compound и написать "докопостроитель" прямо на V7. Притом можно не только строить документацию по форматированным комментариям, но и проверять, какие функции и модули остались без описания, в каких описаниях допущены структурные или синтаксические ошибки, и т.д. По результатам проверки можно тут же (благо это всё происходит внутри V7-базы) выписать штраф ответственному за проект сотруднику ;-).

Можно документировать не только заголовки функций и модулей, а также сложную логику, ветвления, взаимосвязи. И затем на основе всего этого строить документацию с несколькими уровнями детализации, в цветах и красках. Ответить на вопрос "если я вот в этом месте слегка всё раздолбаю, что грохнется в других местах?" будет значительно проще, имея в руках более продвинутый инструмент, нежели "поиск во всех текстах". Честное слово.

На самом деле, никакой фантастики:

• Соглашение о формате комментариев (в виде st-шаблона)
• Соглашение об именовании объектов
• Рекомендации по документированию
• Инструментарий для извлечения документации из MD (в виде набора ert)

Окупятся ли затраты на внедрение такой технологии в рамках конкретного франчайзи-бизнеса – это каждый решает сам. В любом случае, выполнение задач по созданию стандартов (а получается именно что стандарт, пусть и "внутрикорпоративный") пойдёт сотрудникам только на пользу, думать головой всегда полезно. ;-)

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

Конечно, у описанной концепции есть довольно существенный недостаток, на любую бочку мёда найдётся своя ложка гм.. ну, скажем дёгтя (и почему-то обычно красно-жёлтого цвета ;-). Большинство разработок делается на основе типовых, новые релизы которых выходят даже чаще, чем размножаются кошки. Обновление же типовой конфигурации с сохранением своих доработок – это задача из класса "удаление гландов через задний проход, причём бензопилой, причём выключенной бензопилой". Тут и говорить не о чем.

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