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

Подобно правилу Скрытия Информации, принцип Самодокументирования определяет, как следует документировать модули:

Принцип Самодокументирования

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

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

Документация, рассматриваемая здесь, является внутренней документацией о компонентах ПО. Пользовательская документация о выпущенном программном продукте может быть отдельным документом, реализованном в виде печатного текста, либо размещенном на CD-ROM или страницах в Интернете. Как отмечалось при обсуждении вопроса о качестве программного обеспечения, следствием общего принципа самодокументирования является наблюдаемая сейчас тенденция к большему использованию средств диалоговой оперативной подсказки. (См."О документировании" лекция 1)

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

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

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

Главным достижением последних нескольких лет явилось появление стандартов качества ПО. Разработаны сертификаты ISO, стандарт "2167" и его преемники, Модель Полноты Потенциала (Capability Maturity Model), предложенная Институтом программной инженерии (Software Engineering Institute). Но поскольку они брали начало из моделей, используемых в других отраслях знания, они наделены обширным "хвостом" бумажной документации. Некоторые из этих стандартов могли бы оказать значительно большее влияние на качество ПО, (помимо того, что они дают администраторам программного продукта средство для оправданий в случае последующих эксплуатационных неполадок) если бы они включали принцип Самодокументирования.

В этом курсе следствием принципа Самодокументирования является метод документирования классов - модулей при ОО-конструировании ПО, предусматривающий включение документации в сам модуль. Это вовсе не означает, что сам модуль является своей документацией: текст программы обычно содержит слишком много подробностей (это и явилось доводом в пользу скрытия информации). Просто модуль должен содержать свою документацию. (См. "Использование утверждений класса (assertions) для документирования" в лекции 11. См. также лекция 5 курса "Основы объектно-ориентированного проектирования" и последние два упражнения в ней.)

При таком подходе ПО превращается в единственный программный продукт, обеспечивающий его различные представления или облики (views). Один облик, пригодный для компиляции и выполнения, - полный исходный текст модуля. Другой - документация, задающая абстрактный интерфейс модуля, позволяющий разработчикам программного обеспечения создавать модули-клиенты, не знакомясь с содержанием исходного модуля, что соответствует правилу Скрытия Информации. Возможны и другие представления.