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

Описание программы (ГОСТ 19.402-78 ) должно содержать:

1 Общие сведения о программе – полное наименование, обозначение, ее возможные применения, а также программное обеспечение, необходимое для функционирования программы, и языки программирования, на которых она написана. Например:

Программа "Автоматизированное рабочее место разработчика САУ" предназначена для… реализована на… Программа поддерживает…

Программа написана на языке…с использованием компилятора…

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

Программа предназначена для решения задач… Программа представляет собой ядро автоматизированного рабочего места…

Пользователь имеет возможность…, осуществить…, запустить…, проанализировать…, получить результаты анализа и обработки…, построить… и т.п.

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

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

Метод решения может быть представлен:

– в виде системы формул (безусловной или условной);

– в виде словесного изложения последовательности действий;

– в виде их комбинаций.

Описание метода может содержать ограничения на исходные данные, накладываемые методом.

Схемы алгоритмов, программ, данных и систем , приводимые в этом разделе, должны использовать метод пошаговой детализации. Причем уровень детализации должен быть таким, чтобы различные части программы и взаимосвязи между ними были понятны в целом. Другими словами сначала нужно описать обобщенную схему алгоритма, разбив программу логические блоки, а затем подробно рассмотреть схемы алгоритмов работы каждого из этих блоков. Условные обозначения и правила выполнения схем определяются ГОСТ 19.701-90 (Приложение Б) .

В состав программы входят следующие модули:

– пользовательский интерфейс;

– модуль определения путей в графе;

– модуль расчета передаточной функции;

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

– модуль построения реакции на полиномиальное воздействие;

– текстовый редактор.

Интерфейсный модуль построен на двух типах диалогов: диалог "вопрос – ответ" и диалог типа "меню". Интерфейсный модуль управляет…

Модуль определения путей в графе основан на использовании метода… Он является…

Модуль расчета передаточной функции реализует метод… и т.д.

Алгоритм определения путей в графе имеет вид: …

4 Используемые технические средства – типы ЭВМ и устройств, используемых при работе программы. Например:

Программа эксплуатируется на персональном компьютере (ПК) типа IBM PC/AT. Для работы в диалоговом режиме используется экран дисплея, клавиатура и манипулятор типа "мышь". Для поддержки графического режима необходим адаптер S VGA. Входные данные хранятся на гибком и/или жестком дисках. Программа работает под управлением ОС…

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

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

Описание структуры входных данных включает указание типов данных, диапазонов их значений, форматов представления и т.д.

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

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

Используемый метод определения… не может быть использован при…, поэтому эти значения являются недопустимыми, а программа реагирует на них выводом сообщения…

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

Описание структуры выходных данных включает указание типов данных, диапазонов их значений, форматов представления и т.д.

Выходными данными являются:

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

– файлы в одном из графических форматов – копии изображения построенных характеристик (АЧХ, ФЧХ и т.д.);

– текстовые файлы – отчеты о проведенных исследованиях в формате… ;

– диагностика состояния системы и сообщения обо всех возникших ошибках.

В зависимости от особенностей программы допускается введение дополнительных разделов.

Программы для ЭВМ оформляются в соответствии с требованиями Единой системы программной документации (ЕСПД) . ЕСПД - набор ГОСТов, устанавливающих правила оформления, содержание, структуру программных документов.
Данный how-to содержит выдержки из ЕСПД. Полные сведения можно получить непосредственно из ГОСТов.

Краткий алгоритм оформления программы

Кратко алгоритм оформления программы и виды программных документов изображены на рисунке. Более подробно процесс оформления описан далее.

Оформление программного документа

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

Каждый отдельный программный документ оформляется по (общим для всех докуметнов ЕСПД) требованиям ГОСТ 19.101-77 , ГОСТ 19.103-77 , ГОСТ 19.104-78 , ГОСТ 19.105-78 , ГОСТ 19.106-78 , ГОСТ 19.604-78 (более подробное описание данных ГОСТов следует ниже) и ГОСТа для конкретного программного документа.

Общие требования к программным документам. ГОСТ 19.105 - 78

Требования к программным документам, выполненным печатным способом. ГОСТ 19.106 - 78

ГОСТ 19.106-78 устанавливает правила выполнения программных документов для печатного способа выполнения.

Важно отметить, что данный ГОСТ не распространяется на программный документ "Текст программы".

Материалы программного документа должны располагаться в следующей последовательности :

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

В аннотации указывают издание программы, кратко излагают назначение и содержание документа. Если документ состоит из нескольких частей, в аннотации указывают общее количество частей. Содержание документа размещают на отдельной (пронумерованной) странице (страницах) после аннотации, снабжают заголовком «СОДЕРЖАНИЕ», не нумеруют как раздел и включают в общее количество страниц документа.

Форматирование текста:

• Программный документ выполняют на одной стороне листа, через два интервала; допускается через один или полтора интервала.
• Аннотацию размещают на отдельной (пронумерованной) странице с заголовком «АННОТАЦИЯ» и не нумеруют как раздел.
• Заголовки разделов пишут прописными буквами и размещают симметрично относительно правой и левой границ текста.
• Заголовки подразделов записывают с абзаца строчными буквами (кроме первой прописной).
• Переносы слов в заголовках не допускаются. Точку в конце заголовка не ставят.
• Расстояние между заголовком и последующим текстом, а также между заголовками раздела и подраздела должно быть равно:
  • при выполнении документа машинописным способом - двум интервалам.
• Для разделов и подразделов, текст которых записывают на одной странице с текстом предыдущего раздела, расстояние между последней строкой текста и последующим заголовком должно быть равно:
  • при выполнении документа машинописным способом - трём машинописным интервалам.
• Разделы, подразделы, пункты и подпункты следует нумеровать арабскими цифрами с точкой.
• В пределах раздела должна быть сквозная нумерация по всем подразделам, пунктам и подпунктам, входящим в данный раздел.
• Нумерация подразделов включает номер раздела и порядковый номер подраздела, входящего в данный раздел, разделённые точкой (2.1; 3.1 и т. д.).
• При наличии разделов и подразделов к номеру подраздела после точки добавляют порядковый номер пункта и подпункта (3.1.1, 3.1.1.1 и т.д.).
• Текст документа должен быть кратким, четким, исключающим возможность неверного толкования.
• Термины и определения должны быть едиными и соответствовать установленным стандартам, а при их отсутствии - общепринятым в научно-технической литературе, и приводиться в перечне терминов.
• Необходимые пояснения к тексту документа могут оформляться сносками.
• Сноска обозначается цифрой со скобкой, вынесенными на уровень линии верхнего обреза шрифта, например: «печатающее устройство2)...» или «бумага5)».
• Если сноска относится к отдельному слову, знак сноски помещается непосредственно у этого слова, если же к предложению целом, то в конце предложения. Текст сноски располагают в конце страницы и отделяют от основного текста линией длиной 3 см, проведённой в левой части страницы.
• Иллюстрации, если их в данном документе более одной, нумеруют арабскими цифрами в пределах всего документа.
• Формулы в документе, если их более одной, нумеруются арабскими цифрами, номер ставят с правой стороны страницы, в скобках на уровне формулы.
• Значение символов и числовых коэффициентов, входящих в формулу, должны быть приведены непосредственно под формулой. Значение каждого символа печатают с новой строки в той последовательности, в какой они приведены в формуле. Первая строка расшифровки должна начинаться со слова «где», без двоеточия после него.
• В программных документах допускаются ссылки на стандарты (кроме стандартов предприятий), технические условия и другие документы (например, документы органов Государственного надзора, правила и нормы Госстроя СССР). При ссылках на стандарты и технические условия указывают их обозначение.
• Ссылаться следует на документ в целом или на его разделы (с указанием обозначения и наименования документа, номера и наименования раздела или приложения). При повторных ссылках на раздел или приложение указывают только номер.
• В примечаниях к тексту и таблицам указывают только справочные и пояснительные данные.
• Одно примечание не нумеруется. После слова «Примечание» ставят точку.
• Несколько примечаний следует нумеровать по порядку арабскими цифрами с точкой. После слова «Примечание» ставят двоеточие.
• Сокращения слов в тексте и надписях под иллюстрациями не допускаются.
• Иллюстрированный материал, таблицы или текст вспомогательного характера допускается оформлять в виде приложений.
• Каждое приложение должно начинаться с новой страницы с указанием в правом верхнем углу слова «ПРИЛОЖЕНИЕ» и иметь тематический заголовок, который записывают симметрично тексту прописными буквами.

В ГОСТе присутствует образец листа, где указаны поля, места для нумерации страниц и шифра.

Данный документ относится к типу программно-эксплуатационной. Применяется к программе, комплексу, ПАК, программному компоненту или системе.
Целевая аудитория: лица, которые принимают решение о покупке и вводе в эксплуатацию программы. Документ содержит информацию о функциональных возможностях программы и сфере её применения.

ГОСТы и стандарты

Структуру и оформление документа определяется в .
Информационная часть (аннотации и содержания) в соответствии с .

В каких случаях необходим

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

Всю необходимую информацию они смогут получить из этого документа: описание программы и ее применение.

В описании программы и описании применения указываются:

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

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

Структура описания программы (ГОСТ 19.402-78):

1. Общие сведения.
2. Функциональное назначение программы.
3. Описание логической структуры.
4. Технические средства, которые используются.
5. Вызов и загрузка.
6. Входные данные.
7. Выходные данные.

Структура описания применения (ГОСТ 19.502-78):

1. Назначение программы.
2. Условия применения.
3. Описательная часть задачи.
4. Входные и выходные данные.
5. приложения (таблицы, иллюстрации и т.д.).

Вы можете заказать разработку документа или полного комплекта документации на программное обеспечение.

Постановлением Государственного комитета СССР по стандартам от 18 декабря 1978 г. № 3350 срок введения установлен

с 01.01. 1980 г.

1. Настоящий стандарт устанавливает состав и требования к содержанию программного документа «Описание программы», определённого ГОСТ 19.101-77 .

Стандарт полностью соответствует СТ СЭВ 2092-80.

2. Структуру и оформление документа устанавливают в соответствии с ГОСТ 19.105-78 .

Составление информационной части (аннотации и содержания) является обязательным.

3. Описание программы должно содержать следующие разделы:

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

В зависимости от особенностей программы допускается вводить дополнительные разделы или объединять отдельные разделы.

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

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

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

6. В разделе «Описание логической структуры» должны быть указаны:

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

Описание логической структуры программы выполняют с учетом текста программы на исходном языке.

3-6.(Измененная редакция, Изм. № 1).

7. В разделе «Используемые технические средства» должны быть указаны типы электронно-вычислительных машин и устройств, которые используются при работе программы.

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

Допускается указывать адреса загрузки, сведения об использовании оперативной памяти, объем программы.

9. В разделе «Входные данные» должны быть указаны:

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

10. В разделе «Выходные данные» должны быть указаны:

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

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

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

7-12.(Введены дополнительно, Изм. № 1).

* Переиздание (Ноябрь 1987 г.) с Изменением № 1, утвержденным в сентябре 1981 г (ИУС 11-81)

Общие сведения.

Программа называется jane и сохранена в файле jane.dpr. Программа использует вспомогательные модули main, new, dmData, about, сохранённые соответственно в файлах main.pas, new.pas, about.pas, dmData.pas. Программа написана на языке программирования Delphi. Программа использует данные из таблиц базы данных otdel.db, sotrudnik.db, family.db, obrazovanie.db

Функциональное назначение.

Реализация графа диалога.

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

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

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

Рисунок 17. Дерево экранных форм

Описание логической структуры.

Программа управляется событийно. При нажатии на какую-либо кнопку в программу поступает сообщение, при этом вызывается соответствующая процедура-обработчик, которая обрабатывает данное событие. Результаты обработки можно видеть на экране монитора. Например: при нажатии на кнопку “Работа” в форме “Дипломный проект” вызывается процедура, содержащаяся в модуле New, которая скрывает форму “Дипломный проект”, выводит на экран монитора форму “Кадровый учет”, при этом управление передается модулю Main.

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

Рисунок 18. Форма Ввод пароля

Входные и выходные данные.

Входные данные:

название отдела,

ФИО начальника,

ФИО сотрудников, должность,

дата приема на работу,

место последней работы,

стаж на дату приема,

признак наличия образования,

признак наличия семьи,

количество детей,

семейное положение,

даты рождения,

тип образования,

форма обучения,

учебное заведение,

дата окончания,

специальность.

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