Разрабатываемые в квалификационной работе программные документы должны оформляться согласно требованиям стандартов Единой Системы Программной Документации (ЕСПД). Перечень обязательных разрабатываемых программных документов определяется видом квалификационной работы. По заданию руководителя в работе могут разрабатываться и другие программные документы, предусмотренные ЕСПД. В обязательном порядке в работах, связанных с разработкой в том или ином виде программного продукта, должны быть:
- текст программы – запись программы с необходимыми комментариям;
- описание программы – сведения о логической структуре и функционировании программы;
- пояснительная записка (может не оформляться в виде отдельного документа, а соответствующий материал помещаться в текст пояснительной записки самой работы) – описание алгоритма(ов) решения задачи и/или функционирования программы (рекомендуется приводить схемы алгоритмов для пояснения логики решения), обоснование принятых технических и технико-экономических решений;
- руководство пользователя.
В дипломных проектах дополнительно разрабатывается программа и методика испытаний, т.е. требования, подлежащие проверке при испытании программы, а также порядок и методы их (требований) контроля. В проектах или работах, связанных с созданием или исследованием какого-либо алгоритмического языка, приводится описание синтаксиса и семантики этого языка.
Любой программный документ (согласно ГОСТ 19.105–78, 19.106–78) содержит титульную, информационную и основную части. Титульная часть — титульный лист документа (Приложение 9). Информационная часть включает аннотацию (см. Приложение 8) и содержание (оглавление). Аннотация оформляется так же, как аннотация пояснительной записки всей работы и содержит сведения о назначении документа и краткое изложение его основной части. Содержание включает перечень структурных элементов основной части документа с указанием страниц их расположения. Состав основной части программного документа устанавливается стандартом ЕСПД на соответствующий документ.
Программные документы оформляются на листах формата А4 (210х297 мм). Материалы программного документа располагаются в следующей последовательности: титульный лист, аннотация, содержание, текст документа. На титульном листе кроме названия документа и вида указывается его код (обозначение) согласно ГОСТ 19.101-77.
Таблица
Виды программных документов и их коды
| Код | Вид документа | Код | Вид документа |
| Текст программы | Руководство оператора | ||
| Описание программы | Описание языка | ||
| Описание применения | Программа и методика испытаний | ||
| Руководство системного программиста | Пояснительная записка | ||
| Руководство программиста | 90–99 | Прочие документы |
Структура обозначения программного документа для учебных квалификационных работ соответствует структуре обозначений текстовых документов, приведенных в Приложении 8. При оформлении программных документов следует руководствоваться следующими рекомендациями.
Текст программы оформляется согласно требованиям ГОСТ 19.401–78. Информационная часть в общем случае необязательна, но при большом объеме текстовой части целесообразно составлять «ОГЛАВЛЕНИЕ», которое позволяет быстро находить нужную часть программы, ее модуль и т.п. Основная часть документа должна содержать собственно текст программы в символической записи на исходном языке. В тексте программы в обязательном порядке должны содержаться комментарии, объясняющие ее функционирование, используемые структуры данных, логику работы программы и т.п.
Описание программы делается согласно требованиям ГОСТ 19.402–78. Для этого документа составление информационной части (аннотации и содержания) является обязательным. Основная часть документа должна содержать разделы: общие сведения; функциональное назначение; описание логической структуры; используемые технические средства; вызов и загрузка; входные и выходные данные. В зависимости от особенностей программы допускается вводить дополнительные разделы или объединять отдельные разделы.
При описании общих сведений указывается наименование программы, требования к программному обеспечению, необходимому для ее функционирования, используемые для написания программы языки программирования. В функциональном назначении указываются классы решаемых задач и/или назначение программы и сведения о функциональных ограничениях на ее применение.
Основную часть документа составляет раздел “Описание логической структуры”, куда помещается алгоритм программы (приводится схема алгоритма) и его описание, краткое изложение используемых математических и алгоритмических методов, характеризуется структура программы с описанием функций составных частей и связей между ними, а также с другими программами. Описание логической структуры программы обязательно должно быть увязано с текстом программы на исходном языке и имеющимися там комментариями.
В документе должны быть указаны типы вычислительных машин и устройств, которые используются при работе программы, способ вызова программы с соответствующего носителя данных и входные точки в программу. Допускается указывать адреса загрузки, сведения об использовании оперативной памяти, объем программы.
Особое внимание необходимо уделить на описание характера, организации форматов и способ кодирования входных и выходных данных. Особо отмечается необходимость и требования предварительной подготовки входных данных.
Руководство пользователя составляется на основе требований стандарта к таким программным документам, как «Руководство системного программиста» (ГОСТ 19.503–79), «Руководство программиста» (ГОСТ 19.504–79) и «Руководство оператора» (ГОСТ 19.505–79). Поскольку квалификационная работа является учебной работой, то можно составлять единое руководство. Руководитель при составлении задания может потребовать от дипломника оформление этих документов строго по ГОСТ.
Составление информационной части документа (аннотации и содержания) является обязательным. Руководство в основной части должно содержать:
- общие сведения о программе ( назначение и функции программы, сведения о технических и программных средствах, обеспечивающих исполнение данной программы.);
- описание структуры программы и ее составных частей, связи между составными частями и с другими программами, основные характеристики программы (временные характеристики, режим работы и т.п.);
- описание действий по настройке программы и условиям конкретного применения (настройка на состав технических средств, выбор функций и др.), при необходимости приводятся поясняющие примеры;
- описание способов и средств проверки, позволяющих дать общее заключение о работоспособности программы (контрольные примеры, методы прогона, результаты);
- описание последовательности действий, обеспечивающих загрузку, выполнение и завершение программы, описание функций, форматов и возможных вариантов команд, с помощью которых можно производить загрузку и управление выполнением программы, сообщения программы на эти команды, организации входной и выходной информации и, при необходимости, ее кодирования;
- тексты сообщений, выдаваемых в ходе настройки, проверки и выполнения программы, описываются их содержание и действия, предпринимаемые по этим сообщениям.
- последовательность действий оператора, обеспечивающих загрузку, выполнение и завершение программы. Приводится описание функций, форматов и возможных вариантов команд, с помощью которых оператор осуществляет загрузку и управляет выполнением программы, а также ответы программы на эти команды.
Изложение всех этих вопросов рекомендуется оформлять в виде разделов документа и иллюстрировать поясняющими примерами, таблицами, схемами, графиками, размещаемыми в основной части документа или в приложении к нему.
Программа и методика испытаний согласно ГОСТ 19.301–79 может не содержать информационной части (аннотации и содержания). Если документ оказывается объемным, то рекомендуется содержание составлять. В основной части документа указывается: характеристика объекта испытания (наименование и обозначение испытуемой программы); цель испытаний и подлежащие проверке требования к программе и программной документации; состав программной документации, предъявляемой на испытания; технические и программные средства, используемые во время испытаний, и порядок проведения испытаний; описание проверок (тестовых примеров) и ожидаемые результаты испытаний; контрольные распечатки.
В зависимости от особенностей документа допускается вводить дополнительные разделы. Тестовые примеры, контрольные распечатки тестовых примеров, таблицы, графики и т.п. могут быть включены непосредственно в текст руководства или приведены в приложении к нему.