Самодокументирование
Многие новые технологии программирования позволяют получать самодокументированные программы, значительно снижая усилия, необходимые для документирования.
Под документацией мы подразумеваем не тексты рабочей (машинной) программы. Недостаточно также и текстов исходной программы. Документация, подготавливаемая для фазы продолжающейся разработки, должна содержать:
1) хорошо прокомментированный текст программы;
2) схемы, иллюстрирующие проект, и словесное их описание;
3) структурированные словесные описания или схемы процессов, причем первое более предпочтительно;
4) описания данных.
Без всего этого программисту, которому предстоит модифицировать существующую программу, придется решать сложнейшую задачу по определению того, что было сделано до него.
Структурированное словесное описание
Такие описания и читать и понимать легче, чем блок-схемы. Снабженный подробными приложениями, грамотно оформленный, разделенный на модули текст описания усваивается особенно легко, ведь и общая структура текста, и используемые в нем термины вполне понятны любому. Структурированное словесное описание это не программа, но эти понятия близки.
PROCEDURE: PWARN $ display warning message
INPUTS:
LOTMP — time to retry after overtemp condition
LEMI — time to retry after EMI condition
LACT — printer queue overflow flag
OUTPUTS:
none
IF LACT set THEN
IF NOR less than TQR (space unavailable) THEN
clear LACT
set LCODE to 134
call procedure POPMG to display operator message
ENDIF
ENDIF
DO-WHILE LACTX is 0 thru 1
IF EMI is set and CSRTC is greater than or equal to LEMI(LACTX) THEN
set LCODE to 321
call procedure POPMG to display warning message
store the new retry time in LEMI
increment retry counter LRCTR
IF LRCTR greater than or equal 3 THEN
clear the FM! flan
ENDIF
ENDIF
IF OVRTMP is set and CSRTC greater than or equal LOTMP(LACTX) THEN
set LCODE to 320
call procedure POPMG to display warning message
store new retry time in LOTMP
increment retry counter LRCTR
IF LRCTR greater than or equal to 3 THEN
clear OVRTMP flag
ENDIF
ENDIF
END-WHILE
END PROCEDURE-OUTPUT INTERRUPT
Рис. 5.52. Структурированное описание на языке проектирования программ.
На рис. 5.52 приведено структурированное словесное описание, для которого использован язык проектирования программ PDL. Это описание эквивалентно нескольким блок-схемам, которые изображены на рис. 5.53. Словесное описание лучше блок-схем по следующим причинам:
1) оно располагается на одной странице, и его общая структура легко обозрима;
2) оно содержит больше информации, чем блок-схемы.
На рис. 5.54 приведено другое описание с гораздо большим числом комментариев.
![]()
![]()
![]()
Рис. 5.53. Блок-схемы.
PROC SESSION MANAGEMENT * THIS PROCEDURE MANAGES THE
TERMINAL INTERACTION WITH THE USER. LEGAL USER
COMMANDS ARE MOVE AND DELETE *
USE SESSION DATA
DO * PROCESS USER COMMANDS *
GET INPUT (COMMAND) * NEXT USER INPUT *
RUN INPUTCHECK (COMMAND, ERROR)
IF
ERROR = TRUE
THEN
PUT OUTPUT (ERROR)
ELSE * NO ERROR — PROCEED WITH PROCESSING *
IF * DETERMINE TYPE COMMAND *
COMMAND = MOVE
THEN * PROCESS MOVE COMMAND *
INCLUDE MOVE PROCESSING
ELSE * PROCESS DELETE COMMAND *
INCLUDE DELETE PROCESSING
Fl
Fl GET INPUT (SESSION ~ ON)
WHILE * KEEP PROCESSING INPUT COMMANDS AS LONG
AS SESSION ON INDICATOR IS ON (TRUE) *
SESSION ON = TRUE
OD
CORP
DATA SESSION DATA
*ABSTRACT DATA TYPES & COMMENTS *
ATAD
Рис. 5.54. Структурированное описание.
Служебные слова CORP, OD, FI и ATAD представляют собой «закрывающие скобки» для слов PROC, DO, IF и DATA. Если правила ясны, то документы такого типа читаются очень легко.
Строки типа «IF * ОПРЕДЕЛЕНИЕ ТИПА ПРИКАЗА *» необходимо еще будет переводить на язык, с которого можно осуществлять трансляцию, но уже на этом уровне совершенно ясно, что нужно делать. В совокупности с хорошим общим описанием проекта такого рода документация должна быть вполне достаточна для продолжающейся разработки. Документы этого уровня можно обрабатывать с помощью машин, но транслировать их в рабочую программу еще невозможно.
Документация для других целей
Знать, что происходит в программе, должны не только люди, занимающиеся сопровождением, но и многие другие.
Рис. 5.53. Блок-схемы.