Внимание! Если хотите, чтобы мы посвятили рассылку Вам или вашему сайту, то пишите на почту: odin-s@bk.ru
Технический автописатель
Документация – это кубометры вымоченной, размолоченной, высушенной, отбеленной и спрессованной древесины, которые прилагаются к программному и аппаратному обеспечению компьютеров.
"Словарь IT-терминологии"
Программисты ненавидят писать документацию. Заставить программиста подробно и вдумчиво документировать свои разработки – это примерно то же самое, что заставить российского собаковода убирать за своей собакой отходы её жизнедеятельности. Заставить-то можно, но толку всё равно не будет.
Программистов можно понять – если разработку подробно документировать, то это приведёт к ещё большему запутыванию и без того запутанного проекта.
В самом деле: вот мы составили план, вот мы ведём работы. Пишем код и тут же документируем его. Затем (и конечно же вдруг) выясняется, что эта вот хрень работает сосвсем не так, как надо, а заказчик, оказывается, совсем забыл предупредить, что он-то имел в виду не двенадцатиэтажный блочный дом, а двенадцать одноэтажных коттеджей, соединённых подземными туннелями.
Все эти вещи, само собой, выясняются за пару дней до сдачи очередного этапа (а если повезёт, то это будет сдача не этапа, а всего проекта). Люди не спят ночами и переписывают код с такой скоростью, как будто им платят за количество знаков, набиваемое в единицу времени. Времени и желания переписывать ещё и документацию ни у кого, разумеется, не остаётся.
Таким образом, после первого же аврала мы имеем расхождение документации и реального положения дел. Что уже само по себе может стать причиной следующего аврала – даже если над проектом работает всего-то один человек. Портрет программиста, чешущего репу на предмет "блин, и что же я хотел сказать этой вот функцией?" уже давно стал классикой. Ну а принцип "не убирай из проекта непонятный и явно ненужный код, потому что он может оказаться критически важным" давно стал признаком
профессионализма.
Понятно, что речь идёт о технической, внутренней документации, предназначенной исключительно для разработчиков и проектировщиков. User's manual – это отдельная песня и здесь мы её петь не будем.
Получается, что документация в её классическом виде (см. эпиграф) есть не бесполезная трата времени, а скорее вредная трата времени. Вспомните, когда вы последний раз по-серьёзному документировали свои разработки и чем это закончилось.
Вопрос, как заставить программистов документировать код, поддерживать документацию в актуальном состоянии, и чтобы при этом проекту не наносился ущерб, только кажется сложным. Ответ прост, как мычание – документация должна быть частью кода. Выбрасываем код, выбрасывается и документация к нему. Добавляем – добавляется. Переписываем – нужно быть просто страшным лентяем, чтобы не переписать заодно и пару строчек комментария. А страшных лентяев немного, их можно выявлять
и давить, пока маленькие.
Технический способ решения проблемы также давным-давно придуман. Посмотрите на Visual Studio .NET – M$ понадобилось всего-то семь версий среды разработки, чтобы додуматься до форматированных комментариев, которые служат основой для генерации документации к проекту. И, конечно, в M$ это сделали с шиком: XML-тэги, автоподстановки, эргономика. А вот в Perl такая система "документации-в-коде" (POD) существует уже лет сто, хоть и без шика, но вполне в рабочем виде.
К чему я веду этот длинный заморочный базар? К тому, что подобная концепция очень хорошо вписывается в работу с V7. Ситуации, когда над одной конфигурацией в разное время работают разные люди является прямо-таки стандартной. И не только у франчайзи. Кто, что и когда делал? Как связаны модули друг с другом? Для чего нужна та или иная глобальная функция? Чтобы ответить на этот вопрос, нужно читать код.. А код каждый кодер пишет по-своему. Если перенести на бумагу маты, сложенные одними кодерами на других в
процессе разбора логики поведения модулей, то получится лист длиной с пару экваторов, если не больше.
А ведь документировать код не просто, а очень просто:
// HEADER BEGIN // <function id="глПересчетВалюты"> // <author>Василий Пупкин</author> // <update>2002-07-23</update> // <descr>Служебная функция пересчёта курса валют // На входе валюта (справочник), дата (или документ) // и режим (1 - из рублей, 2 - в рубли)</descr> // </function> // HEADER END Функция глПересчетВалюты
( … Набивать тэги руками никто не заставляет: механизм шаблонов V7 для того и нужен, чтобы любые повторяющиеся куски вводить набором двух-трёх букв.
Вытащить из MD все "документальные" куски и построить на их основе структурированное описание конфигурации – это уже дело техники, можно, скажем, взять Compound и написать "докопостроитель" прямо на V7. Притом можно не только строить документацию по форматированным комментариям, но и проверять, какие функции и модули остались без описания, в каких описаниях допущены структурные или синтаксические ошибки, и т.д. По результатам проверки можно тут же (благо это всё происходит внутри
V7-базы) выписать штраф ответственному за проект сотруднику ;-).
Можно документировать не только заголовки функций и модулей, а также сложную логику, ветвления, взаимосвязи. И затем на основе всего этого строить документацию с несколькими уровнями детализации, в цветах и красках. Ответить на вопрос "если я вот в этом месте слегка всё раздолбаю, что грохнется в других местах?" будет значительно проще, имея в руках более продвинутый инструмент, нежели "поиск во всех текстах". Честное слово.
На самом деле, никакой фантастики:
Соглашение о формате комментариев (в виде st-шаблона)
Соглашение об именовании объектов
Рекомендации по документированию
Инструментарий для извлечения документации из MD (в виде набора ert)
И любой сотрудник Вашей конторы, придя к любому клиенту, в считанные минуты получит полное техническое описание конфигурации и сможет быстро сориентироваться в ситуации, не заставляя клиента оплачивать часы чтения кода с умным лицом.
Окупятся ли затраты на внедрение такой технологии в рамках конкретного франчайзи-бизнеса – это каждый решает сам. В любом случае, выполнение задач по созданию стандартов (а получается именно что стандарт, пусть и "внутрикорпоративный") пойдёт сотрудникам только на пользу, думать головой всегда полезно. ;-)
Вот разработка стандарта для V7-сообщества в целом есть задача хотя и очень интересная, но неблагодарная. Такое количество людей никогда не будет действовать по единым правилам, что прямо противоречит смыслу стандартизации.
Конечно, у описанной концепции есть довольно существенный недостаток, на любую бочку мёда найдётся своя ложка гм.. ну, скажем дёгтя (и почему-то обычно красно-жёлтого цвета ;-). Большинство разработок делается на основе типовых, новые релизы которых выходят даже чаще, чем размножаются кошки. Обновление же типовой конфигурации с сохранением своих доработок – это задача из класса "удаление гландов через задний проход, причём бензопилой, причём выключенной бензопилой".
Тут и говорить не о чем.
«Новости, новинки и обзоры серверной, климатической, садовой и техники для дома. Скидки и подарки»:
«Специальное предложение для клиентов ЦОД «Славянский»» Уважаемые клиенты STSS, при покупке сервера Вы получаете скидку в размере 10% на размещение оборудования (collocation) в ЦОД Славянский. ЦОД Славянский предлагает услуги по аренде выделенных серверов (dedicated), стоимость аренды сервера зависит от его конфигурации, уточняйте цены в Отделе продаж ЦОД Славянский...
«Экскурсия в монастырь Новый Иерусалим - 1 час от Москвы» На этой экскурсии Вы побываете в открытых приделах храма: В Успенском приделе (находятся мощи св. мученицы Татианы и святыня крест - мощевик, подаренный монастырю иерусалимскими монахами. Крест содержит частицы Креста Господня и мощей святых, включая евангелиста Марка); в Архангельском приделе увидите список Тихвинской чудотворной иконы Божией матери XVII века и гробницу патриарха Никона в Предтеченском приделе, возле которой происходят чудесные исцеления; в действующей подземной церкви Константина и Елены
с уникальным медным иконостасом (находится кладезь "Живоносный источник"); пройдетесь по монашеской территории - вдоль братских корпусов; побываете в деревянном зодчестве; сможете пройтись по крепостной стене и побывать в Гефсиманской, Сионской и Елизаветинской башнях и в надвратной Входоиерусалимской церкви над Золотыми воротами; у скита патриарха Никона; сможете увидеть реку Иордан (Истра) с ее купелью с рассказом о чудесных исцелениях. Прогулка по монастырскому полю и Гефсиманскому саду, а также вдоль монастырской
стены, где можно увидеть два озера, именуемых Галилейским морем из которых вытекает Кедронский поток...
Общение о компьютерах, серверах, других железках, если вдруг не нашли ответов и просто о компьютерах в нашей жизни. Можете рекламировать свои творения тут, в других разделах реклама будет удаляться...
Вы можете добавить свою новость или статью по адресу (необходимо зарегистрироваться): www.anobis.ru
По вопросам размещения Ваших статей и информации в наших рассылках - пишите нам: odin-s@bk.ru
Давайте поможем строящемуся Храму - приюту для детей! Информация здесь >>>
