ЧЕЛОВЕЧЕСКИЙ ФАКТОР

Содержимое типичного модуля или блока программы

Чтобы программа была самодокументируемой, ее текст должен помимо собственного кода содержать еще и другие многочис­ленные типы информации. В зависимости от конкретной при­кладной системы и от метода проектирования и программирова­ния блоки кода могут представлять собой целостные програм­мы или отдельные модули. В каждой такой программной еди­нице в дополнение к программному коду должна содержаться следующая информация:

1. Идентификатор программного файла в виде системного имени для обращения.

2. Авторская принадлежность: фамилии программистов.

3. Дата создания: число, месяц и год, указывающие, когда программа была впервые помещена в библиотеку программ или включена в сферу конфигурационного управления.

4. Хронология модификаций: даты и соответствующие пояс­нения к каждому внесенному изменению в данный файл. Если процесс формирования запросов на изменения формализован и нужные сведения сохраняются в специальном файле библиоте­ки программ, достаточно указания номера соответствующей за­явки на внесение изменений.

5. Аннотация: описание на естественном языке целевого на­значения программы и основного метода ее разработки. Описы­ваются также связи с другими программными единицами, если эти связи существенны для понимания данной программной единицы.

6. Структуры данных: описание всей информации, внутрен­ней по отношению к данной программной единице, и всех ин­терфейсов с другими блоками, в том числе описания входов, выходов, процедур, прикладных пакетов и вызовов функций.

7. Комментарии: распределенные по строкам основного текс­та программы короткие описания на естественном языке, харак­теризующие функциональное назначение конкретных фрагмен­тов кода. Перечисленные свойства иллюстрируются рис. 5.23 и 5.26.