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

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

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

[x]. Внешнюю, дающую пользователям возможность понять сильные стороны системы и удобство их использования. Необходимость в ней является следствием простоты использования системы.

[x]. Внутреннюю, дающую разработчикам ПО возможность понять структуру и реализацию системы, - следствие требования расширяемости.

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

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

[x]. Включение возможности получения справки проясняет соглашения пользовательского интерфейса. Тем самым облегчается задача авторов руководств пользователей и других форм внешней документации.

[x]. Хороший язык реализации устраняет необходимость большой части внешней документации. Это будет одним из главных требований ОО-нотации, разработанной в этой книге.

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