Программная документация

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

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

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

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

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

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

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

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

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

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

Наконец, вернемся к самой программе. Мы знаем, что при составлении программы на языке ассемблера возможно внесение в нее комментариев и что информация карты, начинающаяся с символа * в первой колонке, целиком рассматривается как комментарий. Во многих хорошо документированных программах комментарии составляют более трех четвертей всего текста программы. Из-за недостатка места мы не могли включить столь подробные комментарии в приводимые в этой книге примеры. Все же некоторые представление о том, как это делается, можно получить из рис. 5.16, где представлена программа из примера рис. 5.10, переписанная с внесением подробных комментариев. Всегда старайтесь так писать программы, чтобы максимально облегчить их понимание.

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

Расскажи друзьям