Правила оформления программной документации

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

Программная документация является неотъемлемым компонентом программного продукта и должна оформляться в соответствии с Единой системой программной документации (ЕСПД — ГОСТ серии 19). В рамках учебных работ допускается заключать всю содержательную часть программной документации в единый «отчёт по программе», при этом формальные требования к оформлению такого отчёта соответствуют требованиям к отчёту по НИР. В данном разделе изложены ключевые моменты государственных стандартов ЕСПД.

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

техническое задание (назначение, область применения программы, требования, предъявляемые к программе);
текст программы (запись программы с необходимыми комментариями);
описание программы (сведения о логической структуре и функционировании программы);
пояснительная записка (схема алгоритма, общее описание алгоритма и/или функционирования программы, обоснование принятых решений);
эксплуатационные документы.

Программный документ «Пояснительная записка» составляется на стадии эскизного или технического проектов программы. Как правило, на стадии рабочего проекта не используется.

К эксплуатационным документам относят:

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

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

Эксплуатационный документ «Описание языка» включается в программную документацию, если разработанный программный продукт реализует некий язык программирования, управления заданиями, организации вычислительного процесса и т. п.

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

Техническое задание

В техническое задание включают:

введение (наименование, краткая характеристика области применения программы);
основания для разработки (документы, на основании которых ведётся разработка, организация, утвердившая документы, дата утверждения, наименование и обозначение темы разработки);
назначение разработки (функциональное и эксплуатационное назначение программы);
требования к программе и программной документации;
технико-экономические показатели;
стадии и этапы разработки;
порядок контроля и приёмки.

Наиболее существенной частью технического задания является раздел «требования…» В этом разделе приводятся:

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

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

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

Программа не должна содержать избыточные элементы (все элементы программы адекватны поставленной задаче: нет циклов, массивов и т. п. элементов, без которых можно обойтись).
Алгоритм должен быть структурирован: для функционального стиля программирования — адекватное разбиение на функции (процедуры), для объектно-ориентированного — адекватная иерархия классов. Каждая функция (метод класса) должна реализовывать ровно одно действие.
У функций (методов классов) должны быть параметры. Следует избегать использования в функциях глобальных переменных.
Программа должна аккуратно использовать память: работать с динамическими массивами, в ней не должно быть неиспользуемых блоков памяти, лишних переменных.
Должны проверятся диапазоны вводимых пользователем значений и параметров, передаваемых между модулями программы.
При использовании в программе каких-либо готовых компонент (библиотечных функций, классов) если функция или метод класса может завершиться неудачей, необходимо обязательно проверять это, не полагаясь на незначительность вероятности такого события.
Программа должна быть конфигурируема (важные параметры программы следует выделить в единый блок).

Текст программы

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

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

Описание программы

Документ «Описание программы» содержит:

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

Описание логической структуры программы следует сопровождать блок-схемой программы.

Документ «Описание программы» может содержать также схемы данных, схемы взаимодействия программ, схемы ресурсов системы и проч., оформленные в соответствии с ГОСТ 19.701-90.

Описание применения

Документ «Описание применения» относится к эксплуатационным документам и состоит из следующих разделов:

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

Руководство системного программиста

Документ «Руководство системного программиста» относится к эксплуатационным документам и включается в программную документацию, если разработанный программный продукт требует обслуживания системным программистом.

Документ состоит из следующих разделов:

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

Руководство программиста

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

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

Руководство оператора

Документ «Руководство оператора» относится к эксплуатационным документам и состоит из следующих разделов:

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

Пример отчёта по программе по дисциплине «алгоритмические языки»: Файл:Ucmd.pdf (160K).