Мифический человеко-месяц или как создаются программные системы

ОглавлениеДобавить в закладки К обложке

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

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

15.6 Важная документация пользователя должна быть вчерне написана до разработки программы, поскольку в ней содержатся основные плановые решения. В ней должны быть описаны девять предметов (см. текст главы).

15.7 Программу нужно поставлять с несколькими контрольными примерами: с допустимыми входными данными, допустимыми на грани возможностей, и с явно недопустимыми входными данными.

15.8 Внутренняя документация программы, предназначенная тому, кто должен ее модифицировать, также должна содержать текстуальный обзор, в котором должны быть описаны пять предметов (см. главу).

15.9 Блок-схема чаще всего напрасно включается в документацию. Подробная пошаговая блок-схема устарела благодаря письменным языкам высокого уровня. (Блок-схема — графический язык высокого уровня.)

15.10 Редко требуется блок-схема более чем на одну страницу — если она вообще нужна. (Стандарт MILSPEC здесь совершенно не прав.)

15.11 Что действительно необходимо — это структурный граф программы без соблюдения стандартов составления блок-схем ANSI.

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

15.13 Для облегчения труда ведения документации есть три важных правила:

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

• Используйте свободное пространство и формат, чтобы показать отношения подчиненности, вложенности и улучшить читаемость.

• Вставляйте в программу необходимую текстовую документацию в виде параграфов комментариев, особенно в заголовках модулей.

15.14 В документации, которой будут пользоваться при модификации программы, объясняйте не только «как», но и «почему». Назначение является решающим для понимания. Даже языки высокого уровня совсем не передают значения.

15.15 Методы самодокументирующегося программирования наиболее полезны и мощны при использовании языков высокого уровня.

Эпилог к первому изданию

E.1 Программные системы являются, возможно, самыми сложными и запутанными (в смысле числа различных типов составляющих) созданиями человека.

E.2 Смоляная яма программной инженерии еще долгое время будет оставаться вязкой.


Логин
Пароль
Запомнить меня