4. Состав и содержание программной документации.

К программным документам относятся документы, содержащие сведения, необходимые для разработки, изготовления, сопровождения и эксплуатации программ. При разработке программной документации рекомендуется ориентироваться на стандартные требования, предъявляемые при сдаче в эксплуатацию разработанных программных комплексов. В основном, эти требования соответствуют государственным и международным стандартам на оформление программной документации. Имеется совокупность международных стандартов, которые в различной степени определяют документирование программных средств. В частности, можно выделить следующие международные стандарты. Во-первых, ГОСТ Р ИСО/МЭК 12207 (ISO 12207), «Процессы жизненного цикла программных средств». В шестом подразделе данного стандарта определены некоторые аспекты процесса документирования. В соответствии с данным стандартом, процесс документирования является процессом формализованного описания информации, созданной в процессе или работе жизненного цикла. В процесс документирования включаются работы, при помощи которых планируют, проектируют, разрабатывают, выпускают, редактируют, распространяют и сопровождают те документы, в которых нуждаются все заинтересованные лица. К заинтересованным лицам относятся администраторы, инженеры и пользователи системы или программного продукта. Процесс документирования состоит из следующих работ:

1.  подготовка процесса;
2. проектирование и разработка;
3. выпуск;
4. сопровождение.

Во-вторых, ГОСТ Р ИСО/МЭК 15910 (ISO 15910), «Пользовательская документация программных средств». Данный стандарт определяет минимально необходимый процесс создания документации пользо­вателя всех видов для программного средства, имеющего интерфейс пользователя. Данные виды охва­тывают печатную документацию (например, руководства пользователя и краткие справочные карты); диалоговую (оперативную) документацию; справочный текст  и системы диалоговой доку­ментации. Стандарт не определяет компо­новку конкретного документа, его содержание и другие аспекты комплектности документации. Одна­ко, данный стандарт устанавливает метод планирования и проведения процесса документирования. В-третьих, ГОСТ Р ИСО/МЭК ТО 9294, «Руководство по управлению документированием ПО». Данный стандарт предназначен для помощи руководителям в обеспечении эффективного проведения документирования при разработке программного обеспечения. Данный стандарт направлен на определение стратегий, стандартов, процедур, ресурсов и планов, которыми должны заниматься сами руководители для того, чтобы эффективно управлять документированием ПО. Руководство по управлению документированием ПО предназначено для применения ко всем типам программного обеспечения, начиная от простейших программ до наиболее сложных систем программного обеспечения. Данное руководство  охватывает все типы программной документации, относящейся ко всем стадиям жизненного цикла ПО. В-четвертых, ANSI/IEEE 829-1991, «Документация при тестировании программ». В данном стандарте предлагается четкая система документирования процессов и результатов тестирования. Она охватывает планирование тестов, их спецификацию и отчеты о результатах тестирования. В плане тестирования рекомендуется описывать цели, объекты, этапы и графики тестирования, состав привлекаемых специалистов и вычислительных ресурсов, номенклатуру оформляемых документов, а также взаимодействие с планами обеспечения качества и управления конфигурацией программного средства. Кроме рассмотренных международных стандартов, имеется комплекс российских стандартов на оформление программной документации. Данный комплекс стандартов получил название «Единая система программной документации» (ЕСПД). В ЕСПД определен перечень  видов программных документов и требования к их оформлению. Всего ЕСПД включает свыше тридцати различных стандартов. Однако не все из перечисленных в ЕСПД документов достаточно часто используются при оформлении программной документации. Как правило, при документировании программного обеспечения используются следующие документы:

во-первых, текст программы;

во-вторых, руководство пользователя;

в-третьих, описание программы;

в-четвертых, программа и методика испытаний.

5. Стандартное документирование текста программы.

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

Во-первых, назначение программы;

Во-вторых, интерфейс документируемой программы с другими программами;

В-третьих, особенности ввода и вывода;

В-четвертых, основные особенности алгоритма.

 Комментарии распределяются по тексту программы неравномерно. Основная их часть пишется в начале программы. Текст программы должен начинаться с комплекса комментариев, который называется паспортом программы (модуля). В паспорте модуля определяются:

во-первых, функции программы;

во-вторых, имя файла, в котором располагается исходный текст;

в-третьих, краткая характеристика входных и выходных параметров.

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

 «Организация цикла по I», «Чтение записи»,

«Проверка A=0» смысла не имеют.

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

6. Стандартный документ “Руководство пользователя”.

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

• назначение программы;
• условия выполнения программы;
• выполнение программного комплекса.

Раздел «Назначение программы», содержит описание предметной области. Рекомендуется описать следующие моменты:

во-первых, для какой задачи используется созданное программное обеспечение;

во-вторых, какие задачи, и в какой мере, связаны с решаемой задачей;

в-третьих, функциональные особенности решения задачи;

в-четвертых, особенности информационного обеспечения.

 Раздел «Условия  выполнения программы» содержит описание требований к вычислительной технике и системному программному обеспечению. Раздел «Выполнение программного комплекса» содержит следующие  подразделы:

Во-первых, подраздел «подготовительные действия», который содержит описание подготовки прикладного программного обеспечения к работе;

Во-вторых, подраздел «основные операции, выполняемые по задаче». Этот подраздел содержит описание основных элементов диалога;

В-третьих, подраздел «примеры реализации основных функций пользователя». В этот подраздел включается описание последовательности операций при выполнении основных функций.

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

7. Стандартный документ “Описание программы”.

Описание программы разрабатывается для программиста, осуществляющего сопровождение созданного программного продукта. Этот документ предусматривает изложение материала,  понятного профессиональному программисту. Описание программы содержит следующие разделы:

во-первых, общие сведения;

во-вторых, функциональное назначение;

в-третьих, описание  логической  структуры   программы;

в-четвертых, используемые   технические   средства;

в-пятых, вызов и загрузка;

в-шестых, входные данные;

в-седьмых, выходные данные.

В разделе «Общие сведения» должны быть указаны следующие сведения:

• обозначение и наименование программы;
• программное обеспечение, необходимое для функционирования программы;
• язык программирования, на котором написана программа.

Кроме того, в этом разделе могут быть определены подходы, используемые при разработке программного обеспечения. Например, применение концепции объектно-ориентированного программирования или использование детерминированного автомата с конечным числом состояний. В разделе «Функциональное назначение» содержится описание основных  функций, выполняемых программным изделием. Кроме того, в этом разделе могут содержаться сведения об ограничениях на применение. B разделе «Описание логической структуры» должны быть указаны:

• алгоритм программы;
• используемые методы;
• структура программы с описанием функций составных частей и связей между ними;
• связи программы с другими программами.

При описании алгоритма программы не всегда целесообразно представлять детальную блок-схему. Излишняя детализация может затруднить понимание алгоритма. Степень детализации должна быть такой, чтобы наглядно показать в динамике взаимодействие основных частей алгоритма. Используемые методы описываются с той степенью детализации, которая достаточна для понимания алгоритма. Например, если в программном средстве используется регрессионный анализ, то это не значит, что необходимо полное описание методов регрессионного анализа. Структурная схема программы позволяет определить статическое разбиение программы на составные части. Она повышает наглядность восприятия. Однако динамика взаимодействия составных частей при описании логической структуры не определяется. Пункт, описывающий связи программы с другими программами, должен однозначно определить интерфейс между различными программами. Если используется ранее разработанная программа, то необходимо сделать ссылку на ее документацию. В разделе «Используемые технические средства» описываются требования к аппаратуре и системному программному обеспечению. В разделе «Вызов и загрузка» описывается подключение программного изделия к работе. В разделе «Входные данные» должны быть указаны следующие сведения: Во-первых, организация и предварительная подготовка входных данных; Во-вторых, формат, описание и способ кодирования входных данных. В частности, описываются используемые базы данных. Кроме того, могут быть определены компоненты, обеспечивающие ввод информации. Наиболее распространенной ошибкой при оформлении данного раздела является стремление заменить описание форматов представления данных конкретным тестовым примером. Для указания совокупности отладочных данных, на которых была проверена корректность выполнения программы, имеется специальный документ, который называется “Программа и методика испытаний”. В разделе «Выходные данные» должны быть указаны следующие сведения:

Во-первых, характер и организация выходных данных;

Во-вторых, формат, описание и способ кодирования выходных данных.

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

8. Стандартный документ “Программа и методика испытаний”.

Документ «Программа и методика испытаний» предназначен для того, чтобы подтвердить готовность разработанного программного продукта. Документ должен подтвердить возможность использования разработанного программного обеспечения в условиях, согласованных с пользователем. В соответствии со стандартом программа и методика испытаний должна включать следующие разделы:

во-первых, объект испытаний;

во-вторых, цель испытаний;

в-третьих, технические требования;

в-четвертых, порядок проведения испытаний;

в-пятых, методы испытаний.

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

Во-первых, требования к программной документации;

Во-вторых, требования к техническим характеристикам.

В подразделе «Требования к программной документации» должны быть указаны требования к комплектности, содержанию и качеству  предъявляемой документации. В подразделе «Требования к техническим характеристикам» должны быть указаны следующие сведения:

• требования к характеристикам программы применительно к условиям эксплуатации;
• требования к информационной и программной совместимости.

В разделе «Порядок проведения испытаний» должны быть указаны следующие сведения:

Во-первых, последовательность испытаний;

Во-вторых, состав  технических средств, необходимых при испытании;

В-третьих, перечень требуемых программных продуктов.

В разделе «Методы испытаний» определяются следующие аспекты:

Во-первых, определяются методологические принципы проведения испытаний;

Во-вторых, описываются методы, используемые при тестировании;

В-третьих, представляются разработанные тесты.

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

Во-первых, цель и назначение теста;

Во-вторых, конкретные значения входных данных;

В-третьих, ожидаемые выходные и промежуточные результаты.