Мифический человеко-месяц или как создаются программные системы
Шрифт:
Третье предложение — включить в программу необходимую текстовую документацию в виде параграфов комментариев. В большинстве программ достаточно иметь построчные комментарии. В программах, отвечающих жестким стандартам организаций на «хорошее документирование», их часто слишком много. Однако даже в этих программах обычно недостаточно параграфов комментариев, которые действительно способствуют понятности и обозримости целого.
Поскольку документация встраивается в используемые программой структуру, имена и форматы, значительную часть этой работы необходимо проделать, когда программу только начинают писать. Но именно тогда и нужно писать документацию.
Некоторые приемы. На рисунке 15.3 показана самодокументирующаяся программа на языке PL/I. [3] Числа в кружочках не являются ее частью, а служат метадокументацией для ссылок при обсуждении.
1. Используйте для каждого запуска свое имя задания и ведите журнал, в котором учитывайте предмет проверки, время и полученные результаты. Если имя состоит из мнемоники (здесь QLT) и числового суффикса (здесь 4), то суффикс можно использовать в качестве номера запуска, связывающего запись в журнале и листинг. При этом для разных прогонов требуются свои карты задания, но их можно делать колодами с дублированием постоянных данных.
2. Используйте мнемонические названия программы, включающие идентификатор версии — в предположении, что будет несколько версий. Здесь индекс — две младшие цифры года.
3. Включите текстовое описание в качестве комментариев к PROCEDURE.
4. Для документирования алгоритмов ссылайтесь, где можно, на литературу. Это экономит место, адресует к более полному освещению, чем можно дать в программе, и дает возможность знающему читателю пропустить ссылку, оставляя уверенность, что он вас поймет.
5. Покажите связь с алгоритмом, описанным в книге: а) изменения; б) особенности использования; в) представление данных.
6. Объявите все переменные. Используйте мнемонику. Используйте комментарии для превращения оператора DECLARE в полноценную легенду. Обратите внимание, что он уже содержит имена и описания структур, нужно лишь дополнить его описаниями назначения. Сделав это здесь, вы избежите отдельного повторения имен и структурных описаний.
7. Поставьте метку в начале инициализации.
8. Поставьте метки перед группами операторов, соответствующие операторам алгоритма, описанного в книге.
9. Используйте отступы для показа структуры и группирования.
10. Вручную поставьте стрелки, показывающие логический порядок операторов. Они очень полезны при отладке и внесении изменений. Их можно поместить на правом поле места для комментариев и сделать частью вводимого в машину текста.
11. Вставьте строчные комментарии для пояснения всего, что неочевидно. При использовании изложенных выше приемов они окажутся короче и малочисленней, чем обычно.
12. Помещайте несколько операторов на одной строке или один оператор на нескольких строках в соответствии с логической группировкой, а также чтобы показать связь с описанием алгоритма.
Возражения. Каковы недостатки такого подхода к документированию? Они существуют, и в прежние времена были существенными, но сейчас становятся мнимыми.
Рис. 15.3 Самодокументирующаяся программа
Самым серьезным возражением является увеличение размера исходного текста, который нужно хранить. Поскольку практика все более тяготеет к хранению исходного кода в активных устройствах, это вызывает
Однако одновременно мы движемся к хранению в активных устройствах текстовых документов, доступ к которым и изменение осуществляется с помощью компьютеризированных текстовых редакторов. Как указывалось выше, слияние текста и программы сокращает общее количество хранимых символов.
Аналогичное возражение вызывает аргумент, что самодокументирующиеся программы требуют больше ввода с клавиатуры. В печатном документе требуется, по меньшей мере, одно нажатие на клавишу для каждого символа на каждый черновой экземпляр. В самодокументирующейся программе суммарное количество символов меньше, и на один символ приходится меньше нажатий на клавиши, так как черновики не перепечатываются.
А что же блок-схемы и структурные графы? Если используется только структурный граф самого высокого уровня, он вполне может содержаться в отдельном документе, поскольку редко подвергается изменениям. Но конечно, его можно включить в исходный текст программы в качестве комментария, что будет благоразумно.
В какой мере описанные выше приемы применимы для программ на языке ассемблера? Я думаю, что базовый подход документирования применим всюду. Свободным пространством и форматами можно пользоваться с меньшей степенью свободы, и поэтому они используются не так гибко. Имена и объявления структур, несомненно, можно использовать. Очень могут помочь макросы. Интенсивное использование параграфов комментарием является хорошей практикой в любом языке.
Но подход на основе самодокументирования стимулирован применением языков высокого уровня и обретает наибольшую мощь и наивысшее оправдание в языках высокого уровня, используемых в режиме он-лайн, будь то в пакетном режиме или интерактивно. Как я доказывал, такие языки и системы очень сильно облегчают жизнь программистов. Поскольку машины сделаны для людей, а не люди для машин, их использование оправдано как с экономической точки зрения, так и чисто по-человечески.
Глава 16 Серебряной пули нет — сущность и акциденция в программной инженерии
Нет ни одного открытия ни в технологии, ни в методах управления, одно только использование которого обещало бы в течение ближайшего десятилетия на порядок повысить производительность, надежность, простоту разработки программного обеспечения.
Резюме[1]
Создание программного обеспечения всегда включает в себя существенные задачи — моделирование сложных концептуальных структур, составляющих абстрактный программный объект, и второстепенные задачи — создание представлений этих абстрактных объектов с помощью языков программирования и отображение их в машинные языки с учетом ограничений по памяти и скорости. В прошлом рост продуктивности программирования по большей части достигался благодаря устранению искусственных преград, делавших второстепенные задачи чрезмерно трудными, например, жестких аппаратных ограничений, неудобных языков программирования, нехватки машинного времени. Какая часть работы разработчиков программного обеспечения все еще связана со второстепенными, а не с существенными обстоятельствами? Если она занимает менее 9/10 всех затрат, то, даже сведя все второстепенные затраты к нулю, мы не получим роста производительности на порядок величин.