Системы документирования

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

Код без документации не стоит ни копейки

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

Недостаточное документирование влечет за собой финансовые последствия:

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

Кроме явных денежных потерь, возникают менее очевидные функциональные сложности:

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

Низкий уровень документирования, создавая иллюзию экономии, в лучшем случае переносит текущие затраты на будущее. Зачастую под сомнением оказываются все усилия, потраченные на разработку.

Принципы

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

  • конечные пользователи;
  • контент–менеджеры;
  • системные администраторы;
  • программисты — пользователи API;
  • программисты ядра системы.

Конечного пользователя не заинтересует документация по программному ядру и наполнению контентом. Но разработчику — пользователю API, так или иначе, придется работать с документацией для сисадмина или для конечного пользователя. Чем ниже уровень слоя, тем потенциально больший объем находящейся "сверху" документации потребует внимания.

Разбиение документации по слоям усложняет процесс ее создания, требуя отдельные:

  • средства создания;
  • литературный стиль;
  • методы доступа.

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

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

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

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

Решения

В своей работе Nixteam практикует общепринятые подходы к созданию документации, используя широкоизвестные пакеты:

  • POD и NaturalDocs для языка программирования Perl;
  • Doxygen для компилируемых языков типа C, C++, Java;
  • LaTeX для сложных интеграционных проектов;
  • Wiki для базы знаний, как правило, обслуживающей контент–менеджеров и иногда конечных пользователей.

При разработке крупных проектов мы создаем мини-сайты, повышающие удобство пользования и обновления документации, отдельные разделы которых освещают:

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

Автоматизация процесса документирования достигается путем:

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

К процессу документирования можно отнести и содержащиеся во внутренних стандартах кодирования требования к оформлению и выбору имен объектов кода (самодокументируемый код).

Есть два способа создания дизайна программы. Один из них, это сделать его настолько простым, что в нем, очевидно, не будет недостатков. Другой способ — сделать его настолько запутанным, что в нем не будет очевидных недостатков.

Чарльз Энтони Ричард Хоар