Общие требования к структуре программных документов

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

Титульный лист разрабатывается на каждый программный документ, за исключением технического задания на курсовое (дипломное) проектирование. Допускается также не разрабатывать титульный лист на спецификацию, а также на схему алгоритма (программы, данных, системы), если они располагаются на одном-двух листах ‑ в этом случае основная надпись выполняется по форме и правилам, предусмотренным ЕСКД.

В аннотации приводят сведения о назначении документа и краткое изложение его основной части, объем аннотации – не более 10 строк текста (для пояснительной записки – не более 20 строк). Содержание включает перечень записей о структурных элементах (разделы, подразделы, для текста программы – модули) основной части документа. Информационная часть не разрабатывается для технического задания, спецификации и схем алгоритмов (данных, программ, системы). Допускается также не разрабатывать информационную часть для программных документов, оформленных в виде приложений к пояснительной записке. Разделы АННОТАЦИЯ и СОДЕРЖАНИЕ не нумеруют.

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

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

4.3.3. Отдельные программные документы учебных проектов выполняются, как правило, в виде приложений к основному документу – пояснительной записке, располагаемых после иллюстрирующих приложений (см. п.4.3.1). На титульном (первом) листе приложения в правом верхнем углу указывается слово ПРИЛОЖЕНИЕ (с порядковым номером, если их несколько), нумерация листов в иллюстрирующих приложениях – сквозная с основным документом, в приложениях – документах – самостоятельная. Все приложения и их наименования (заголовки) перечисляются в информационной части (содержании) пояснительной записки, а в основной ее части должны присутствовать ссылки на каждое из них.

Требования к содержанию и оформлению текстовых программных документов

Отдельные виды текстовых программных документов выполняют в соответствии с ГОСТ 19.201-78, 19.202-78, 19.301-78, 19.401-78, 19.402-78, 19.404-78, 19.502-78, 19.503-79, 19.504-79, 19.505-79.

Спецификация

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

Основная часть спецификации содержит текст, разбитый на графы:

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

– «Наименование» ‑ для наименований разработанных и заимствованных документов на данный комплекс, полных наименований программы и основного документа для входящих комплексов и компонентов;

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

Ширина граф, соответственно ‑ 80, 70 и 30 мм, высота строк – 7..10 мм.

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

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

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

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

Техническое задание на разработку учебных программных изделий оформляется в виде «Задания на курсовое (дипломное) проектирование» по соответствующим формам и правилам и включается в пояснительную записку листом со вторым порядковым номером.

В разделе «Исходные данные» необходимо указывать требования к функциональным характеристикам программы, необходимый состав (параметры) технических средств, а также требования к программной (информационной) совместимости.

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

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

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

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

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

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

Документ включает следующие разделы основной части, содержащие необходимую информацию:

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

функциональное назначение – классы (виды) решаемых задач, сведения о функциональных ограничениях на применение;

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

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

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

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