Источник: http://hare.ru / Источник:
Hare.ru @ КБ Никита Зайцев (WildHare)
Документация -это кубометры вымоченной, размолоченной, высушенной, отбеленной и спрессованной древесины, которые прилагаются к программному и аппаратному обеспечению компьютеров.
"Словарь IT-терминологии"
Программисты ненавидят писать документацию. Заставить программиста подробнои вдумчиво документировать свои разработки -это примерно то жесамое, что заставить российского собаковода убирать за своей собакой отходыеё жизнедеятельности. Заставить-то можно, но толку всё равно не будет.
Программистов можно понять -если разработку подробнодокументировать, то это приведёт к ещё большему запутыванию и безтого запутанного проекта.
В самом деле: вот мы составили план, вот мы ведём работы. Пишем код и тут же документируем его. Затем (и конечно же вдруг) выясняется, что эта вот хрень работает сосвсем не так, как надо, а заказчик, оказывается, совсем забыл предупредить, чтоон-то имел в виду не двенадцатиэтажный блочный дом, а двенадцать одноэтажныхкоттеджей, соединённых подземными туннелями.
Все эти вещи, само собой, выясняются за пару дней до сдачи очередного этапа(а если повезёт, то это будет сдача не этапа, а всего проекта). Люди не спятночами и переписывают код с такой скоростью, как будто им платят за количествознаков, набиваемое в единицу времени. Времени и желания переписывать ещё и документацию ни у кого, разумеется, не остаётся.
Таким образом, после первого же аврала мы имеем расхождение документации и реального положения дел. Что уже само по себе может стать причиной следующего аврала -даже если над проектом работает всего-то один человек.Портрет программиста, чешущего репу на предмет "блин, и что же я хотел сказатьэтой вот функцией?" уже давно стал классикой. Ну а принцип "не убирай из проекта непонятныйи явно ненужный код, потому что он может оказаться критически важным" давностал признаком профессионализма.
Понятно, что речь идёт о технической, внутренней документации, предназначеннойисключительно для разработчиков и проектировщиков. User's manual -этоотдельная песня и здесь мы её петь не будем.
Получается, что документация в её классическом виде (см. эпиграф) есть не бесполезная трата времени, а скорее вредная трата времени. Вспомните, когда вы последнийраз по-серьёзному документировали свои разработки и чем это закончилось.
Вопрос, как заставить программистов документировать код, поддерживать документациюв актуальном состоянии, и чтобы при этом проектуне наносился ущерб, только кажется сложным. Ответ прост, как мычание –документация должна быть частью кода. Выбрасываем код, выбрасывается идокументация к нему. Добавляем -добавляется. Переписываем –нужно быть просто страшным лентяем, чтобы не переписать заодно и пару строчек комментария. А страшных лентяев немного, их можно выявлять и давить, покамаленькие.
Технический способ решения проблемы также давным-давно придуман. Посмотритена Visual Studio .NET -M$ понадобилось всего-то семь версийсреды разработки, чтобы додуматься до форматированных комментариев, которыеслужат основой для генерации документации к проекту. И, конечно, в M$ этосделали с шиком: XML-тэги, автоподстановки, эргономика. А вот в Perl такая система "документации-в-коде" (POD) существует уже лет сто, хоть и без шика,но вполне в рабочем виде.
К чему я веду этот длинный заморочный базар? К тому, что подобная концепцияочень хорошо вписывается в работу с V7. Ситуации, когда над одной конфигурациейв разное время работают разные люди является прямо-таки стандартной. И нетолько у франчайзи. Кто, что и когда делал? Как связаны модули друг с другом?Для чего нужна та или иная глобальная функция? Чтобы ответить на этот вопрос,нужно читать код.. А код каждый кодер пишет по-своему. Если перенести на бумагуматы, сложенные одними кодерами на других в процессе разбора логики поведениямодулей, то получится лист длиной с пару экваторов, если не больше.
А ведь документировать код не просто, а очень просто:
Вытащить из MD все "документальные" куски и построить на их основе структурированноеописание конфигурации -это уже дело техники, можно, скажем,взять Compound и написать"докопостроитель" прямо на V7. Притом можно не только строить документацию по форматированным комментариям, но и проверять, какие функции и модули осталисьбез описания, в каких описаниях допущены структурные или синтаксические ошибки, и т.д.По результатам проверки можно тут же (благо это всё происходит внутри V7-базы)выписать штраф ответственному за проект сотруднику ;-).
Можно документировать не только заголовки функций и модулей, а также сложнуюлогику, ветвления, взаимосвязи. И затем на основе всего этого строить документациюс несколькими уровнями детализации, в цветах и красках. Ответить на вопрос"если я вот в этом месте слегка всё раздолбаю, что грохнется в других местах?" будетзначительно проще, имея в руках более продвинутый инструмент, нежели "поиск вовсех текстах". Честное слово.
На самом деле, никакой фантастики:
Окупятся ли затраты на внедрение такой технологии в рамках конкретного франчайзи-бизнеса -это каждый решает сам. В любом случае, выполнениезадач по созданию стандартов (а получается именно что стандарт, пусть и"внутрикорпоративный") пойдёт сотрудникам только на пользу, думать головойвсегда полезно. ;-)
Вот разработка стандарта для V7-сообщества в целом есть задача хотя иочень интересная, но неблагодарная. Такое количество людей никогда не будетдействовать по единым правилам, что прямо противоречит смыслу стандартизации.
Конечно, у описанной концепции есть довольно существенный недостаток, на любуюбочку мёда найдётся своя ложка гм.. ну, скажем дёгтя (и почему-то обычно красно-жёлтого цвета ;-). Большинство разработок делаетсяна основе типовых, новые релизы которых выходят даже чаще, чем размножаютсякошки. Обновление же типовой конфигурации с сохранением своихдоработок -это задача из класса "удаление гландов через задний проход, причём бензопилой, причём выключенной бензопилой". Тут и говорить не о чем.
Но вот для оригинальных конфигураций концепция автодокументированиябудет, как мне кажется, отличной заменой традиционному "вордописанию". Причёмне только для тиражных, но и для заказных тоже. Грамотно документированный код поможет разработчику избежать традиционного вопроса "а что же я хотел сказатьэтой вот функцией". . .
Автомобили
Бухгалтерия, учет и отчетность