Используют ли программисты документацию?

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

Понимание практики проектирования программ — первый шаг к разработке эффективных решений, которые в наибольшей степени отвечают требованиям процесса создания, поддержки и совершенствования программных продуктов. Проведя ряд исследований, авторы постарались выяснить, каких правил придерживаются программисты при использовании и обновлении документации. Цель исследователей заключалась в том, чтобы как можно более точно разобраться в происходящем и смоделировать процесс использования, определения полезности и дальнейшего сопровождения документации, обеспечив, таким образом, более эффективное принятие решений и выбор инструментальных средств разработчиками и менеджерами проектов. Результаты исследования подтверждают достаточно очевидную гипотезу: поддерживая и совершенствуя свои программы, их авторы, как правило, не следят за полнотой и своевременным обновлением документации.

Исследования

Первое исследование построено на основе опросов, проведенных в 12 частных компаниях и одном госучреждении. Опрос участников проводился попарно, с тем чтобы создать им более комфортные и естественные условия, опросный лист был разделен на три части: базовая информация, анализ задач и пожелания в отношении инструментальных средств.

Второе исследование проводилось в крупной телекоммуникационной компании [2, 3]. В нем принимали участие специалисты, занимающиеся технической поддержкой и развитием мощной и приносящей неплохую прибыль системы управления телекоммуникациями, которая была написана на высокоуровневом языке собственной разработки. Исследование состояло из четырех компонентов. Сначала, опубликовав анкету в Web, мы попросили программистов рассказать, чем конкретно они занимаются. На втором этапе на протяжении 14 недель осуществлялось подробное знакомство с деятельностью одного из программистов. На третьем мы тайно контролировали один рабочий час девяти программистов. И наконец, нами была собрана статистика использования инструментальных средств в масштабе всей компании.

В последнем исследовании были обобщены результаты ответов на 50 вопросов, в которых нашли отражение многие аспекты, связанные с документацией [4, 5].

Полезность документации и поддержка ее в актуальном состоянии

Первое и, пожалуй, главное: исследования подтвердили, что программисты не следят за поддержанием документации в актуальном состоянии. Рис. 1 обобщает ответы специалистов на следующий вопрос: «Какое время, исходя из вашего опыта, требуется на внесение необходимых изменений в документацию при модернизации программного обеспечения?» (Заметьте, что лишь 25 из 48 респондентов ответили на данный вопрос). Если не принимать во внимание документацию, описывающую процедуру тестирования и проверки качества (тест-планы и контрольные примеры), можно сказать, что программисты крайне редко обновляют документы. Но даже когда такое случается, с момента внесения изменений в код до соответствующего обновления документации проходит обычно несколько недель. Из 45 опрошенных 44% в какой-то степени и 24% полностью согласны с утверждением о том, что «по сравнению с текущим состоянием программного обеспечения документация всегда является устаревшей».

Рис. 1. Период между внесением в систему изменений и соответствующим обновлением документации

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

Но несмотря на явно недостаточное внимание, уделяемое поддержке, даже устаревшая или не вполне точная документация может оказаться весьма полезной. Из 45 респондентов 53% в какой-то степени, а 28% полностью разделяют это суждение. Благодаря опросу мы получили оценку программистами точности различных типов документов, а также информацию о частоте, с которой они обращаются к документации. Соотношение между точностью документов различных типов и частотой, с которой программисты обращаются к документации, представлено в таблице 1.

Самая тесная взаимосвязь между точностью и частотой обращения у документов, описывающих процедуры тестирования и контроля качества. В несколько меньшей степени это касается документов, отражающих предъявляемые к программному обеспечению требования, а также особенности архитектуры и рабочего проекта. Частота обращения к спецификациям практически не зависит от их точности. Приведенное соотношение показывает, что чем ближе мы подбираемся к реальному коду, тем более высокие требования предъявляются программистами к точности документации.

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

Применимость документации

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

Результаты опроса показывают, что особая роль документации отводится только при выполнении отдельно взятых задач.

Слово и дело

Необходимо понимать, что результаты нашего опроса отражают лишь отношение программистов к документации, которое вовсе необязательно соответствует реальному характеру ее использования. К примеру, 6% опрошенных сотрудников телекоммуникационной компании сообщили, что тратят много времени на чтение документации, а 50% отметили, что больших временных затрат требует изучение исходного кода. При более подробном обследовании той же самой компании выяснилось, что программисты тратят на чтение документации лишь 3% своего времени: из 357 зарегистрированных событий с обращением к документации было связано только 12. Из этого можно сделать вывод, что документация используется с меньшей степени, чем заявлено. Тем не менее, отношение к документации свидетельствует о том, что в работе программистов ей отводится заметная роль.

Приглашение к дискуссии

На основании проведенных исследований мы сделали два основных вывода.

Своевременность. Нужно ли требовать от программистов педантичного обновления документации? Большинство методологий предписывают разработку документации различных типов, которая должна составляться и использоваться программистами. Но где свидетельства того, что предписываемые процессы действительно работают? Большинство из них основано на субъективных суждениях. Многие программные проекты не доводятся до конца или выходят за рамки отведенного бюджета, однако практика говорит о том, что ошибки следует искать в основном в области слабого управления и неумения четко сформулировать предъявляемые требования, а вовсе не в устаревшей или неполной документации. Исследования показали, что даже устаревшая документация обладает определенной ценностью.

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

Рассмотрим, к примеру, системы диагностики ошибок. Результаты опроса свидетельствуют о том, что программисты воспринимают их в качестве очень важных хранилищ архивной информации. Документация систем поиска и исправления ошибок постоянно обновляется, потому что разработчики понимают ее значимость. Если для устранения ошибки не требуется серьезных усилий, программист просто добавляет небольшой комментарий, и поддержка осуществляется в полуавтоматическом режиме. Комментарии на уровне кода актуальны, потому что мысли в них выражены лаконично, и располагаются они именно «там, где надо». В результате, усилия по техническому сопровождению сводятся к минимуму. Контрольные примеры также поддерживаются в актуальном состоянии, поскольку обладают простой структурой и важны для проверки правильности работы системы. В отличие от этого для спецификаций и требований к программному обеспечению характерна гораздо более сложная и многообразная структура. Таким образом, программисты считают обновление данных документов менее важной задачей, особенно если учесть, что абстрагирование на высоком уровне сохраняет свою значимость даже в случае устаревания каких-то деталей.

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

Все это говорит о том, что для повышения значимости документации необходимо искать способы ее упрощения, расширения ее возможностей, а еще лучше. Самая важная информация не должна занимать много места. Нужно упростить процедуру обновления документации, возможно, переведя ее в полуавтоматический режим.

Кто-то, наверное, возразит, что программисты не обновляют документацию из-за природной лени. Многие менеджеры уже пытались противопоставить этому ужесточение дисциплины, заставляя программистов своевременно обновлять документы. Но мы полагаем, что программистов нельзя называть ленивыми в общепринятом смысле этого слова, просто для них характерна дисциплина несколько иного сорта. Сознательно или подсознательно они формируют для себя некие критерии оценки, приходя к выводу, что имеет смысл обновлять только отдельные виды документации.

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

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

Литература

Тимоти Летбридж (tcl@site.uottawa.ca) — профессор университета Оттавы. Занимается исследованием способов, упрощающих людям понимание и манипулирование сложной информацией, в том числе и программным обеспечением. Входит в состав управляющего комитета Computing Curriculum — Software Engineering. Джанис Сингер (Janice.singer@nrc-cnrc.gc.ca) работает когнитивным психологом в Национальном научно-исследовательском совете при Канадской ассоциации разработчиков программного обеспечения.

Эндрю Форвард (aforward@dc.com) — системный аналитик компании Deloitte Consulting.

Timothy Lethbridge, Janice Singer, Andrew Forward, How Software Engineers Use Documentation: The State of the Practice. IEEE Software, November/December 2003. IEEE Computer Society, 2003, All rights reserved. Reprinted with permission.

Документация: хорошо, плохо и ужасно

«Хорошо»

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

«Плохо»

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

«Ужасно»

• Значительная часть документации не внушает доверия.