Документирование

Документирование представляет собой этап разработки ПО, которым, часто пренебрегают. Вместе с тем правильно составленная документация полезна не только на этапах отладки и тестирования, но исключительно важна на этапах сопровождения и внесения изменения. При необходимости хорошо документированной программой легко воспользоваться снова. Работа с недокументированной программой обычно требует столько дополнительных усилий, что программисту может оказаться легче написать программу заново.

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

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

Важной составляющей программной документации являются комментарии. Однако они не исключают необходимости использований правильного стиля программирования. Программа с Четкой структурой и удачно выбранными именами частично является самодокументи-руемой. Комментарии должны пояснять смысл команд, а не просто повторять их значение. На рис. 6.17 и 6.18 приведена одна и та же программа на языке ассемблера Intel 8080, в одном из вариантов которой комментарии являются плохими, а в другом составлены удачно (программа отыскивает максимальный элемент массива, который расположен начиная с ячейки BLKST и длина которого задана в ячейке 

 

 
LENG).
 
LDA LENG
LENG в A
MOV В, А
А в В
LXI Н, BLKST
Послать BLKST в H
NEWMX: MOV А, М
М в А
NEXTE: INX Н
Н = Н + 1
DCR В
В = В— 1
JZ DONE
Если 0, идти К DONE
CMP м
сравнить с М
JC NEWMX
Если П ЕРЕ НОС =1, идти kNEWMX
JMP NEXTE
Идти к NEXTE
DONE: STA MAX
МАХ = А
HLT
 
 
LDA
LENG
; Счетчик = длина массива
 
 
MOV
В, А
■ '
 
 
LXI
Н, BLKST
4 Начало массива данных
 
NEWMX:
MOV
А, м
; Элемент является новым
 
 
 
 
; максимальным
 
NEXTE:
INX
н
 
 
 
DCR
в
 
 
 
JZ
DONE
 
 
 
CMP
М
; Максимальный элемент больше те­
 
 
 
 
кущего?
 
 
JC
NEWMX
; Нет, заменить максимальный
 
 
JMP
NEXTE
; Да, перейти к следующему элементу
 
DONE:
STA
МАХ
; Запомнить максимум
 
 
HLT
 
 
 
 
Рис. 6 18. Хорошо документированная программа
 

При составлении комментариев необходимо соблюдать следующие правила:

 

1. Комментарии должны пояснять действие, выполняемое командой или группой команд, а не просто объяснять смысл кодов Ьпераций.

2. Комментарии должны быть возможно более ясными. Счедует избегать всяких сокращений и неясных аббревиатур, хотя и не обязательно писать развернутые фразы.

3. Комментировать следует основные действия. Программа с пространными комментариями трудно воспринимается. Стандартные конструкции (управление циклом или операции индексации) нужно пояснить только в тех случаях, когда они выполняются необычным образом.

4. Комментарии следует помещать достаточно близко к соответствующим операторам. Программист должен выработать стандартную форму задания комментариев: повторяемость не является большим недостатком в комментариях. Вместе с тем всякие вариации сбивают с толку.

5. Комментарии должны соответствовать последней версии программы. Наличие комментариев, относящихся к предыдущей версии программы, хуже, чем их отсутствие.

6. Комментарии должны быть четкими. Более подробные объяснения должны быть перенесены в справочное руководство.

Программист должен научиться правильно использовать комментарии. Он должен спросить себя, какие объяснения понадобились бы ему для понимания данной программы, и после этого составить соответствующие комментарии. Подобные систематизированные комментарии могут оказаться полезными на всех этапах разработки ПО.

Карты памяти представляют собой сведения, о распределении памяти в каждой программе. Использование таких карт предохраняет от взаимного наложения различных процедур, облегчает передачу параметров и помогает определить требуемый объем памяти и место расположения подпрограмм, таблиц и рабочих областей. Карты памяти особенно важны при разработке ПО для микропроцессоров, поскольку в таких разработках память программ и данных (ПЗУ и ОЗУ) используется раздельно, а выделение-адресов осуществляется на этапе разработки аппаратной части проекта. Кроме того, необходимо сохранить распределение памяти (особенно более дорогого ПЗУ) и точно знать размещение в памяти некоторых параметров, которые потребуется изменить на месте в соответствии с особенностями конкретного применения.

Список параметров и спецификаций является составной частью любой программы для ЭВМ. Такие списки не только обеспечивают объяснение смысла каждого из параметров и значений различных операций, но и содержат спецификации типов. Наличие подобных списков не исключает необходимости объяснения параметров в комментариях к самим программам.

Карточки библиотечных программ могут содержать описания подпрограмм, которые могут использоваться во вновь разрабатываемых программах. В таких карточках программист должен дать назначе ние программы, форматы входных и выходных данных, требования программы к памяти, времени и РОН, описание параметров и контрольный пример, иллюстрирующий работу программы. На рис. 6.19 приведен пример типичной библиотечной программы, которая может быть реализована как подпрограмма или макрокоманда.

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

Разработка документации требует много времени, поэтому программист должен выполнять эту работу параллельно с проектированием, кодированием, отладкой и тестированием ПО. Рассмотренные в настоящей главе методы проектирования программы позволяют облегчить их документирование. В свою очередь, хорошая документация упрощает сопровождение и перепроектирование и существенно облегчает разработку программ, которые придется составлять в будущем.