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