JК
Мифический человеко-месяц или как создаются программные системы :: Брукс Фредерик
Страница: 248 из 2998 Внутренняя документация программы, предназначенная тому, кто должен её модифицировать, также должна содержать текстуальный обзор, в котором должны быть описаны пять предметов (см. главу).
15.9 Блок-схема чаще всего напрасно включается в документацию. Подробная пошаговая блок-схема устарела благодаря письменным языкам высокого уровня. (Блок-схема — графический язык высокого уровня.)
15.10 Редко требуется блок-схема более чем на одну страницу — если она вообще нужна. (Стандарт MILSPEC здесь совершенно не прав.)
15.11 Что действительно необходимо — это структурный граф программы без соблюдения стандартов составления блок-схем ANSI.
15.12 Чтобы обеспечить обновление документации, важно включить её в исходный текст программы, а не держать отдельным документом.
15.13 Для облегчения труда ведения документации есть три важных правила:
• Как можно больше используйте для документирования обязательные части программы, такие как имена и объявления.
• Используйте свободное пространство и формат, чтобы показать отношения подчинённости, вложенности и улучшить читаемость.
• Вставляйте в программу необходимую текстовую документацию в виде параграфов комментариев, особенно в заголовках модулей.
15.14 В документации, которой будут пользоваться при модификации программы, объясняйте не только «как», но и « почему ». Назначение является решающим для понимания. Даже языки высокого уровня совсем не передают значения.
15.15 Методы самодокументирующегося программирования наиболее полезны и мощны при использовании языков высокого уровня.
15.9 Блок-схема чаще всего напрасно включается в документацию. Подробная пошаговая блок-схема устарела благодаря письменным языкам высокого уровня. (Блок-схема — графический язык высокого уровня.)
15.10 Редко требуется блок-схема более чем на одну страницу — если она вообще нужна. (Стандарт MILSPEC здесь совершенно не прав.)
15.11 Что действительно необходимо — это структурный граф программы без соблюдения стандартов составления блок-схем ANSI.
15.12 Чтобы обеспечить обновление документации, важно включить её в исходный текст программы, а не держать отдельным документом.
15.13 Для облегчения труда ведения документации есть три важных правила:
• Как можно больше используйте для документирования обязательные части программы, такие как имена и объявления.
• Используйте свободное пространство и формат, чтобы показать отношения подчинённости, вложенности и улучшить читаемость.
• Вставляйте в программу необходимую текстовую документацию в виде параграфов комментариев, особенно в заголовках модулей.
15.14 В документации, которой будут пользоваться при модификации программы, объясняйте не только «как», но и « почему ». Назначение является решающим для понимания. Даже языки высокого уровня совсем не передают значения.
15.15 Методы самодокументирующегося программирования наиболее полезны и мощны при использовании языков высокого уровня.