Источник:
Hare.ru @ КБ
Никита Зайцев (WildHare)
Документация -это кубометры вымоченной, размолоченной,
высушенной, отбеленной и спрессованной древесины,
которые прилагаются к программному и аппаратному
обеспечению компьютеров.
Словарь IT-терминологии
Программисты ненавидят писать документацию. Заставить программиста подробно и вдумчиво документировать свои разработки -это примерно то же самое, что заставить российского собаковода убирать за своей собакой отходы её жизнедеятельности.
Заставить-то можно, но толку всё равно не будет.
Программистов можно понять -если разработку подробно документировать, то это приведёт к ещё большему запутыванию и без того запутанного проекта.
В самом деле: вот мы составили план, вот мы ведём работы. Пишем код и тут же документируем его. Затем (и конечно же вдруг) выясняется, что эта вот хрень работает сосвсем не так, как надо, а заказчик, оказывается, совсем забыл предупредить, что он-то имел в виду не двенадцатиэтажный блочный дом, а двенадцать одноэтажных коттеджей, соединённых подземными туннелями.
Все эти вещи, само собой, выясняются за пару дней до сдачи очередного этапа (а если повезёт, то это будет сдача не этапа, а всего проекта). Люди не спят ночами и переписывают код с такой скоростью, как будто им платят за количество знаков, набиваемое в единицу времени.
Времени и желания переписывать ещё и документацию ни у кого, разумеется, не остаётся.
Таким образом, после первого же аврала мы имеем расхождение документации и реального положения дел. Что уже само по себе может стать причиной следующего аврала -даже если над проектом работает всего-то один человек.
Портрет программиста, чешущего репу на предмет блин, и что же я хотел сказать этой вот функцией? уже давно стал классикой. Ну а принцип не убирай из проекта непонятный и явно ненужный код, потому что он может оказаться критически важным давно стал признаком профессионализма.
Понятно, что речь идёт о технической, внутренней документации, предназначенной исключительно для разработчиков и проектировщиков. User’s manual -это отдельная песня и здесь мы её петь не будем.
Получается, что документация в её классическом виде (см. эпиграф) есть не бесполезная трата времени, а скорее вредная трата времени. Вспомните, когда вы последний раз по-серьёзному документировали свои разработки и чем это закончилось.
Вопрос, как заставить программистов документировать код, поддерживать документацию в актуальном состоянии, и чтобы при этом проекту не наносился ущерб, только кажется сложным. Ответ прост, как мычание – документация должна быть частью кода.
Выбрасываем код, выбрасывается и документация к нему. Добавляем -добавляется.
Переписываем – нужно быть просто страшным лентяем, чтобы не переписать заодно и пару строчек комментария.
А страшных лентяев немного, их можно выявлять и давить, пока маленькие.
Технический способ решения проблемы также давным-давно придуман. Посмотрите на Visual Studio .NET -M$ понадобилось всего-то семь версий среды разработки, чтобы додуматься до форматированных комментариев, которые служат основой для генерации документации к проекту.
ДАВНО МЫ ТАК НЕ РЖАЛИ ► MORNING POST
И, конечно, в M$ это сделали с шиком: XML-тэги, автоподстановки, эргономика. А вот в Perl такая система документации-в-коде (POD) существует уже лет сто, хоть и без шика, но вполне в рабочем виде.
К чему я веду этот длинный заморочный базар? К тому, что подобная концепция очень хорошо вписывается в работу с V7.
Ситуации, когда над одной конфигурацией в разное время работают разные люди является прямо-таки стандартной. И не только у франчайзи.
Кто, что и когда делал? Как связаны модули друг с другом?
Для чего нужна та или иная глобальная функция? Чтобы ответить на этот вопрос, нужно читать код..
А код каждый кодер пишет по-своему. Если перенести на бумагу маты, сложенные одними кодерами на других в процессе разбора логики поведения модулей, то получится лист длиной с пару экваторов, если не больше.
А ведь документировать код не просто, а очень просто: // HEADER BEGIN
//
// Василий Пупкин
// 2002-07-23
// Служебная функция пересчёта курса валют
// На входе валюта (справочник), дата (или документ)
// и режим (1 — из рублей, 2 — в рубли)
//
// HEADER END
ФункцияглПересчетВалюты( . . . Набивать тэги руками никто не заставляет: механизм шаблонов V7 для того и нужен, чтобы любые повторяющиеся куски вводить набором двух-трёх букв.
Вытащить из MD все документальные куски и построить на их основе структурированное описание конфигурации -это уже дело техники, можно, скажем, взять Compound и написать докопостроитель прямо на V7. Притом можно не только строить документацию по форматированным комментариям, но и проверять, какие функции и модули остались без описания, в каких описаниях допущены структурные или синтаксические ошибки, и т.д.
По результатам проверки можно тут же (благо это всё происходит внутри V7-базы) выписать штраф ответственному за проект сотруднику ;-).
Можно документировать не только заголовки функций и модулей, а также сложную логику, ветвления, взаимосвязи. И затем на основе всего этого строить документацию с несколькими уровнями детализации, в цветах и красках.
Ответить на вопрос если я вот в этом месте слегка всё раздолбаю, что грохнется в других местах? будет значительно проще, имея в руках более продвинутый инструмент, нежели поиск во всех текстах. Честное слово.
На самом деле, никакой фантастики:
- Соглашение о формате комментариев (в виде st-шаблона)
- Соглашение об именовании объектов
- Рекомендации по документированию
- Инструментарий для извлечения документации из MD (в виде набора ert)
И любой сотрудник Вашей конторы, придя к любому клиенту, в считанные минуты получит полное техническое описание конфигурации и сможет быстро сориентироваться в ситуации, не заставляя клиента оплачивать часы чтения кода с умным лицом.
Окупятся ли затраты на внедрение такой технологии в рамках конкретного франчайзи-бизнеса -это каждый решает сам. В любом случае, выполнение задач по созданию стандартов (а получается именно что стандарт, пусть и внутрикорпоративный) пойдёт сотрудникам только на пользу, думать головой всегда полезно. 
Вот разработка стандарта для V7-сообщества в целом есть задача хотя и очень интересная, но неблагодарная. Такое количество людей никогда не будет действовать по единым правилам, что прямо противоречит смыслу стандартизации.
Конечно, у описанной концепции есть довольно существенный недостаток, на любую бочку мёда найдётся своя ложка гм.. ну, скажем дёгтя (и почему-то обычно красно-жёлтого цвета ;-). Большинство разработок делается на основе типовых, новые релизы которых выходят даже чаще, чем размножаются кошки.
Обновление же типовой конфигурации с сохранением своих доработок -это задача из класса удаление гландов через задний проход, причём бензопилой, причём выключенной бензопилой. Тут и говорить не о чем.
p
Но вот для оригинальных конфигураций концепция автодокументирования будет, как мне кажется, отличной заменой традиционному вордописанию. Причём не только для тиражных, но и для заказных тоже. Грамотно документированный код поможет разработчику избежать традиционного вопроса а что же я хотел сказать этой вот функцией. . .
