15.8 Внутренняя документация программы, предназначенная тому, кто должен ее модифицировать, также должна содержать текстуальный обзор, в котором должны быть описаны пять предметов (см. главу).
15.9 Блок-схема чаще всего напрасно включается в документацию. Подробная пошаговая блок-схема устарела благодаря письменным языкам высокого уровня. (Блок-схема - графический язык высокого уровня.)
15.10 Редко требуется блок-схема более чем на одну страницу - если она вообще нужна. (Стандарт MILSPEC здесь совершенно не прав.)
15.11 Что действительно необходимо - это структурный граф программы без соблюдения стандартов составления блок-схем ANSI.
15.12 Чтобы обеспечить обновление документации, важно включить ее в исходный текст программы, а не держать отдельным документом.
15.13 Для облегчения труда ведения документации есть три важных правила: - Как можно больше используйте для документирования обязательные части программы, такие как имена и объявления. - Используйте свободное пространство и формат, чтобы показать отношения подчиненности, вложенности и улучшить читаемость. - Вставляйте в программу необходимую текстовую документацию в виде параграфов комментариев, особенно в заголовках модулей.
15.14 В документации, которой будут пользоваться при модификации программы, объясняйте не только "как", но и "почему". Назначение является решающим для понимания. Даже языки высокого уровня совсем не передают значения.
15.15 Методы самодокументирующегося программирования наиболее полезны и мощны при использовании языков высокого уровня.
Эпилог к первому изданию
E.1 Программные системы являются, возможно, самыми сложными и запутанными (в смысле числа различных типов составляющих) созданиями человека.
E.2 Смоляная яма программной инженерии еще долгое время будет оставаться вязкой.
Глава 19 "Мифический человеко-месяц" двадцать лет спустяЯ не знаю другого способа судить о будущем, как с помощью прошлого.
ПАТРИК ГЕНРИ
Опираясь на прошлое, невозможно планировать будущее.
ЭДМУНД БЕРК
Для чего понадобилось юбилейное двадцатое издание?
Самолет гудел в ночи, направляясь к Лагардии. Облака и сумрак скрыли все интересное для глаза. Документ, который я читал, был неинтересным. Однако мне не было скучно. Сидящий рядом попутчик читал "Мифический человеко-месяц", и я ожидал, когда словом или жестом он выдаст свое впечатление. В конце концов, когда мы уже выруливали к выходу, я не выдержал:
- Как вам эта книга? Советуете прочесть?
- Хм, в ней нет ничего, чего я не знал бы раньше.
Я решил не представляться.
Почему "Мифический человеко-месяц" выжил? Почему с ним до сих пор считаются в современной практике программирования? Почему его читательская аудитория выходит за пределы сообщества программистов-разработчиков, а книга порождает статьи, цитаты и письма не только разработчиков программ, но и юристов, врачей, психологов, социологов? Каким образом книга, написанная 20 лет назад об опыте разработки программ, имевшем место 30 лет назад, может до сих пор быть актуальной и даже полезной?