Программное обеспечение и его разработка - Фокс Джозеф М.

Многие новые технологии программирования позволяют получать самодокументированные программы, значительно снижая усилия, необходимые для документирования.

Под документацией мы подразумеваем не тексты рабочей (машинной) программы. Недостаточно также и текстов исходной программы. Документация, подготавливаемая для фазы продолжающейся разработки, должна содержать:

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 приведено другое описание с гораздо большим числом комментариев.

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 * ОПРЕДЕЛЕНИЕ ТИПА ПРИКАЗА *» необходимо еще будет переводить на язык, с которого можно осуществлять трансляцию, но уже на этом уровне совершенно ясно, что нужно делать. В совокупности с хорошим общим описанием проекта такого рода документация должна быть вполне достаточна для продолжающейся разработки. Документы этого уровня можно обрабатывать с помощью машин, но транслировать их в рабочую программу еще невозможно.

Знать, что происходит в программе, должны не только люди, занимающиеся сопровождением, но и многие другие.