Основы объектно-ориентированного программирования

         

О документации


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

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

Документацию не следует считать независимой частью проекта. Предпочтительнее в максимально возможной степени создавать самодокументируемое ПО. Это справедливо для всех трех видов документации:

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



Содержание раздела