что такое описание программы
Что такое описание программы
Описание программы (ГОСТ 19.402-78 [8] ) должно содержать:
1 Общие сведения о программе – полное наименование, обозначение, ее возможные применения, а также программное обеспечение, необходимое для функционирования программы, и языки программирования, на которых она написана. Например:
Программа «Автоматизированное рабочее место разработчика САУ» предназначена для… реализована на… Программа поддерживает…
Программа написана на языке…с использованием компилятора…
2 Функциональное назначение – назначение программы и общее описание функционирования программы, ее основные характеристики, сведения об ограничениях, накладываемых на область применения программы. Например:
Программа предназначена для решения задач… Программа представляет собой ядро автоматизированного рабочего места…
Пользователь имеет возможность…, осуществить…, запустить…, проанализировать…, получить результаты анализа и обработки…, построить… и т.п.
3 Описание логической структуры – используемые методы, алгоритмы программы, описание структуры и логики программы ( c привязкой к тексту программы на исходном языке) и ее составных частей, их функций и связей между ними, а также связи программы с другими программами. Содержание этого раздела должно быть конкретным и опираться на текст программы.
Выбор метода решения предполагает определение теоретической возможности решения задачи и нахождение формального правила его получения. Данный этап плохо формализуется, что связано с чрезвычайно широким многообразием задач и методов их решения.
Метод решения может быть представлен:
– в виде системы формул (безусловной или условной);
– в виде словесного изложения последовательности действий;
– в виде их комбинаций.
Описание метода может содержать ограничения на исходные данные, накладываемые методом.
В состав программы входят следующие модули:
– модуль определения путей в графе;
– модуль расчета передаточной функции;
– модуль построения амплитудно- и фазочастотных характеристик;
– модуль построения реакции на полиномиальное воздействие;
Интерфейсный модуль построен на двух типах диалогов: диалог «вопрос – ответ» и диалог типа «меню». Интерфейсный модуль управляет…
Модуль определения путей в графе основан на использовании метода… Он является…
Модуль расчета передаточной функции реализует метод… и т.д.
Алгоритм определения путей в графе имеет вид: …
4 Используемые технические средства – типы ЭВМ и устройств, используемых при работе программы. Например:
Программа эксплуатируется на персональном компьютере (ПК) типа IBM PC/AT. Для работы в диалоговом режиме используется экран дисплея, клавиатура и манипулятор типа «мышь». Для поддержки графического режима необходим адаптер S VGA. Входные данные хранятся на гибком и/или жестком дисках. Программа работает под управлением ОС…
5 Вызов и загрузка – способ вызова программы с соответствующего носителя данных и входные точки в программу, а также имя загрузочного модуля, сведения об использовании оперативной памяти, объем программы и описание всей процедуры вызова и загрузки системы. Например:
6 Входные данные – характер, организация и предварительная подготовка входных данных, их формат, описание и способ кодирования.
Описание структуры входных данных включает указание типов данных, диапазонов их значений, форматов представления и т.д.
В этом же разделе должно приводиться перечисление аномалий во входных данных (значения, для которых нельзя применять реализуемый метод решения) и реакций программы на них.
Входными данными для программы является текстовый файл, описывающий расширенную матрицу инциденций графа исследуемой системы. Этот файл имеет следующую структуру…
Используемый метод определения… не может быть использован при…, поэтому эти значения являются недопустимыми, а программа реагирует на них выводом сообщения…
7 Выходные данные – характер и организация выходных данных, их формат, описание и способ кодирования.
Описание структуры выходных данных включает указание типов данных, диапазонов их значений, форматов представления и т.д.
Выходными данными являются:
– выводимая на экран графическая и текстовая информация (результаты анализа системы);
– файлы в одном из графических форматов – копии изображения построенных характеристик (АЧХ, ФЧХ и т.д.);
– текстовые файлы – отчеты о проведенных исследованиях в формате… ;
– диагностика состояния системы и сообщения обо всех возникших ошибках.
В зависимости от особенностей программы допускается введение дополнительных разделов.
Содержание разделов допускается иллюстрировать пояснительными примерами, таблицами, схемами, графиками, примерами и т.п.
Что такое описание программы
Единая система программной документации
Unified system for program documentation. Program description.
Дата введения 1980-01-01
Постановлением Государственного комитета CCCР по стандартам от 18 декабря 1978 г. N 3350 дата введения установлена 01.01.80
ИЗДАНИЕ (январь 2010 г.) с Изменением N 1, утвержденным в сентябре 1981 г. (ИУС 11-81).
1. Настоящий стандарт устанавливает состав и требования к содержанию программного документа «Описание программы», определенного ГОСТ 19.101-77.
Стандарт полностью соответствует СТ СЭВ 2092-80*.
(Измененная редакция, Изм. N 1).
2. Структуру и оформление документа устанавливают в соответствии с ГОСТ 19.105-78.
Составление информационной части (аннотации и содержания) является обязательным.
3. Описание программы должно содержать следующие разделы:
описание логической структуры;
используемые технические средства;
В зависимости от особенностей программы допускается вводить дополнительные разделы или объединять отдельные разделы.
4. В разделе «Общие сведения» должны быть указаны:
обозначение и наименование программы;
программное обеспечение, необходимое для функционирования программы;
языки программирования, на которых написана программа.
5. В разделе «Функциональное назначение» должны быть указаны классы решаемых задач и (или) назначение программы и сведения о функциональных ограничениях на применение.
6. В разделе «Описание логической структуры» должны быть указаны:
структура программы с описанием функций составных частей и связи между ними;
связи программы с другими программами.
Описание логической структуры программы выполняют с учетом текста программы на исходном языке.
3-6. (Измененная редакция, Изм. N 1).
7. В разделе «Используемые технические средства» должны быть указаны типы электронных вычислительных машин и устройств, которые используются при работе программы.
8. В разделе «Вызов и загрузка» должны быть указаны:
способ вызова программы с соответствующего носителя данных;
входные точки в программу.
Допускается указывать адреса загрузки, сведения об использовании оперативной памяти, объем программы.
9. В разделе «Входные данные» должны быть указаны:
характер, организация и предварительная подготовка входных данных;
формат, описание и способ кодирования входных данных.
10. В разделе «Выходные данные» должны быть указаны:
характер и организация выходных данных;
формат, описание и способ кодирования выходных данных.
11. Допускается содержание разделов иллюстрировать пояснительными примерами, таблицами, схемами, графиками.
12. В приложение к описанию программы допускается включать различные материалы, которые нецелесообразно включать в разделы описания.
7-12. (Введены дополнительно, Изм. N 1).
Электронный текст документа
подготовлен АО «Кодекс» и сверен по:
Единая система программной документации:
Описание программы и описание применения
Данный документ относится к типу программно-эксплуатационной. Применяется к программе, комплексу, ПАК, программному компоненту или системе.
Целевая аудитория: лица, которые принимают решение о покупке и вводе в эксплуатацию программы. Документ содержит информацию о функциональных возможностях программы и сфере её применения.
ГОСТы и стандарты
Структуру и оформление документа определяется в ГОСТ 19.105-78.
Информационная часть (аннотации и содержания) в соответствии с ГОСТ 19.502-78.
В каких случаях необходим
Документ необходим для информирования потенциальных пользователей и покупателей о назначении программы и способах применения. Больше подходит для менеджеров (специалистов, системных администраторов), которые самостоятельно принимают решение о приобретении программы и вводе её в эксплуатацию.
Всю необходимую информацию они смогут получить из этого документа: описание программы и ее применение.
Содержание документа
В описании программы и описании применения указываются:
Задачи, которые решает программа;
Затрачиваемые ресурсы для работы;
Вводная информация;
Выходные данные.
Акцент делается на описательной части программы, её функциях и назначении. В меньшей степени на описании применения. Делается описание именно о возможностях программы и задач, которая она решает, а не её внутреннего устройства. При определённых особенностях программы допускается объединять разделы или вводить новые (дополнительные).
Структура описания программы (ГОСТ 19.402-78):
1. Общие сведения.
2. Функциональное назначение программы.
3. Описание логической структуры.
4. Технические средства, которые используются.
5. Вызов и загрузка.
6. Входные данные.
7. Выходные данные.
Структура описания применения (ГОСТ 19.502-78):
1. Назначение программы.
2. Условия применения.
3. Описательная часть задачи.
4. Входные и выходные данные.
5. приложения (таблицы, иллюстрации и т.д.).
Вы можете заказать разработку документа или полного комплекта документации на программное обеспечение.
Опыт применения ЕСПД
Введение
Основная задача этого текста — рассказать, что такое Единая система программной документации (ЕСПД) и как эти стандарты применять на практике. Начну с рассказа о том, какие бывают стандарты, и закончу опытом применения каждого из ЕСПДшных стандартов в отдельности.
В свое время, когда я только начинал работать программистом, часто приходилось слышать “напиши, пожалуйста, документацию к своей программе”. Я честно все описывал, отдавал начальнику, после чего начинался сеанс черной магии. Начальник через некоторое время меня вызывал и начинал мычать нечленораздельные звуки, мять распечатку моего “самого лучшего” текста в руках, бегая глазами. Общий смысл его мычания заключался в том, что получилось “не то”, “не так”, и “посмотри, как делают другие”. Так как никакого другого ответа из него вытянуть было невозможно, я шел за примерами документов к “другим”. Как правило, это были веселые ребята, смысл речей которых заключался в том, что “вот примеры”, “вообще то по ГОСТу” и “это все никому не нужно”. Так я узнал впервые, что программист может соприкоснуться со страшными ГОСТами.
Поразительно, что среди многих десятков моих коллег, очень неглупых программистов, не было никого, кто бы относился к ГОСТам по другому. Даже те несколько человек, которые их знали и, вроде как, даже умели оформлять документы, относились к ним презрительно-формально. Ситуация, когда даже люди, ответственные за управление разработкой не понимают, зачем нужны ГОСТы и как их применят, встречается на многих предприятиях, сплошь и рядом. Да, были и компании, в которых понимали, чем “Описание программы” отличается от “Описания применения”, но таких было явное меньшинство. В интернете вообще господствует точка зрения, что ГОСТы для программистов — это явный рудимент, и нужны только если “нагибают” под них. Эскизный проект считают “сравнительно честным способом отъемы лишних дензнаков у заказчика”. Вникнуть и разобраться пришлось относительно недавно — в процессе разработки системы управления требованиями, заточенной под отечественную специфику. Документацию которая, разумеется, должна генерировать “по ГОСТу”.
Здесь я хочу сосредоточиться только на одной теме, с которой приходиться иметь дело программисту в отечественных предприятиях, особенно в НИИ — на наборе стандартов ЕСПД. Не считаю себя большим знатоком ЕСПД — есть люди, которые десятки лет по нему работают, и наверняка меня поправят. Статья скорее пытается набросать контуры «дорожной карты» для тех, кто только входит в курс дела.
Стандарты
Системы обозначений на каждом уровне и в каждой организации свои, для каждого случая придется разбираться отдельно. Чтобы быстро понять, “чей” стандарт перед глазами, можно использовать шпаргалку.
Итак: стандарты бывают международные, межгосударственные(региональные) и национальные. ГОСТ, как мы выяснили, это региональный стандарт. ГОСТы имеют достаточно запутанную, на мой взгляд, систему обозначений. Полностью она изложена в ГОСТ Р 1.5-2004, я приведу минимум, что бы в ней ориентироваться. Во первых, надо различать обозначение ГОСТа и его классификацию. Обозначение — это, грубо говоря, уникальный идентификатор стандарта. Код по классификатору — это вспомогательный код, помогающий найти стандарт или определить, к какой области знаний он относиться. Классификаторов может быть много, в основном используются два: КГС (классификатор государственных стандартов) и его наследник ОКС (общероссийский классификатор стандартов). Например: “ГОСТ Р 50628—2000“ — это обозначение стандарта.По обозначению понятно только то, что он принят в 2000 году. Он имеет код по ОКС “33.100;35.160”: т.е. “33” — раздел “Телекоммуникации, аудио, видео”, “100” — подраздел “электромагнитная совместимость”. Однако он также входит в ветвь классификатора 35.160. “35” — “Информационные технологии. Машины конторские”, “160” — “Микропроцессорные системы. ”. А по КГС он имеет код “Э02”, что означает “Э” — “Электронная техника, радиоэлектроника и связь”, “0” — “Общие правила и нормы по электронной технике, радиоэлектронике и связи”, и т.д.
19.001-77. Общие положения
Описывает правила присвоения обозначений стандартов в серии ЕСПД. В практической жизни не нужен.
19.102-80. Схемы алгоритмов и программ. Правила выполнения.
Описывает правила построения и оформления алгоритмов. Использует обозначения из 19.103. В моей практике был нужен единственный раз, когда при сертификационная лаборатория уперлась по формальному признаку, что нужна именно схема алгоритма. С моей точки зрения, классические блок-схемы двумя ногами в прошлом, и единственно, где остались более-менее уместными, это если при изложении автор хочет акцентировать внимание читателя именно на алгоритме.
19.003-80. Схемы алгоритмов и программ. Обозначения условные графические
Приведены графические обозначения допустимых типов элементов блок-схемы. Нужен, если используются блок-схемы.
19.004-80. Термины и определения.
Скудный глоссарий. Из интересного — содержит формальные определения программного и эксплуатационного документов.
19.005-85. Р-схемы алгоритмов и программ
Практически забытый язык. В свое время Р-схемы широко использовались в ракетно-космической отрасли, став стандартом де-факто для написания программ управления пусками и моделирования запусков. Однако ныне этот язык полностью предан забвению. В своей работе я ни разу не сталкивался с Р-схемами. Хотя по сравнению с блок-схемами они имеют заметные преимущества: компактны, подходят для визуализации нелинейных алгоритмов (например, классов в С++) или структур данных. При этом в интернете информации по ним практически нет: мне показались полезными вот этот и вот этот сайты. В любом случае, если бы сейчас мне пришлось вставлять в программную документацию схему алгоритма, я бы выбрал Р-схемы, а не блок-схемы.
19.101-77. Виды программ и программных документов
Содержит таблицу соответствия вида документа его коду, а также деление видов документов на эксплуатационные и программные. Вводится понятие комплекса и компонента. Больше ничего полезного нет.
19.102-77. Стадии разработки
Важный и нужный стандарт, в котором описаны виды документов и приведены коды видов программных документов. Этот стандарт (совместно с 19.103-77) является одним из ключей к “разгадке” обозначений документов подобных АБВГ.10473-01 32 01-1.
В стандарте вводится понятие комплекса и компонента (на ряде предприятий добавляют третий вид — комплект, когда речь идет о несвязанных программных элементах), дается разделение: какие документы эксплуатационные, какие нет.
Следует аккуратно относиться к таблице 4, в которой показано, какой документ на какой стадии разработки выполняется. Стадии разработки обычно регламентируются в стандартах на выполнения ОКР, и там-же указывается, какие документы нужно предъявлять заказчику на каждом этапе.
19.102-77. Стадии разработки
На моей памяти этот стандарт не применялся ни разу: кто что делает на каком этапе и чем отчитывается прописывается в ТТЗ или делается отсылка к ГОСТам, где это прописано более четко (например, ГОСТ РВ 15.203). При этом для новичка он содержит неплохой в своей лаконичности конспект работ на основных этапах ОКР.
19.103-77. Обозначения программ и программных документов
Нужен, в основном, для того, что бы научиться читать обозначения документов подобных приведенному выше. Однако понимание схемы обозначений полезно в случае, когда приходиться выходить за рамки типовых работ: к примеру, помнить, что документы с кодами после 90 — пользовательские, т.е. любые. В моей практике мы выпускали документ 93, который назвали “Ведомость программной документации”, 96 документ — “Инструкция по сборке”.
Распространенное словосочетание “вариант исполнения” в ЕСПД отсутствует, и заменяется “номером редакции”. С одной стороны, это не совсем корректно: номер редакции задумывался для отслеживания эволюции программы: вначале выходит первая редакция, потом, к примеру, после доработки — вторая. Но на практике, когда нужно выпустить версию ПО для нескольких операционных систем (кросс-платформенное ПО), другого выхода нет. Точнее — есть, но неправильный: присвоить версии для каждой операционки свое обозначение — и закладывать в архив несколько дисков с исходниками (по числу операционок), разрабатывать (фактически — копировать) весь комплект документации и т.д… Т.е. чистой воды бестолковая и сбивающая с толку деятельность. Решение в виде присвоения версии под каждую операционку своего номера редакции позволяет часть документов сделать общими.
В ЕСПД используется смущающее многих программистов обозначение исходных текстов программы и результата сборки “документами”. Документ “текст программы”, согласно 19.101-77, имеет обозначение 12. Дальше принято, что исходники обозначаются как 12 01 — т.е. 01(первый) документ вида 12, а бинарники — как 12 02 — т.е. второй документ вида 12. В ряде случаев для сборки программы требуются дополнительные инструментальные средства — компиляторы, генераторы инсталляторов и т.д. Т.е. программы, которые не входят в поставку, но нужны для сборки. Решением может быть их обозначение как 12 03 — т.е. третий документ вида 12.
19.104-78. Основные надписи
19.105-78. Общие требования к программным документам
Вводится общая структура документа, не зависящая от способа его исполнения. Т.е. еще в 1978 году было заложено в стандарт, что документ может быть не обязательно бумажным. В частности, вводиться понятие содержания для полностью электронных документов. Для бумажного исполнения, распространенного в то время, был принят ГОСТ 19.106-78.
В настоящее время к этому стандарту приходиться обращаться очень редко: разве что забывается порядок следования основных частей документа.
19.106-78. Общие требования к программным документам, выполненным печатным способом
В следующих частях планирую уже добраться до конца списка стандартов ЕСПД.
Техническая документация
разработка техдокументации по ГОСТ
Описание программы по ГОСТ 19.402-78
Настоящий стандарт устанавливает состав и требования к содержанию программного документа «Описание программы», определенного ГОСТ 19.101-77.
Стандарт полностью соответствует СТ СЭВ 2092-80 [из п. 1 ГОСТ 19.402-78]
Структуру и оформление документа устанавливают в соответствии с ГОСТ 19.105-78. Составление информационной части (аннотации и содержания) является обязательным [из п. 2 ГОСТ 19.402-78]
Описание программы должно содержать следующие разделы:
В зависимости от особенностей программы допускается вводить дополнительные разделы или объединять отдельные разделы [из п. 3 ГОСТ 19.402-78]
Общие сведения
В разделе «Общие сведения» должны быть указаны:
[из п. 4 ГОСТ 19.402-78]
Функциональное назначение
Описание логической структуры
Описание логической структуры программы выполняют с учетом текста программы на исходном языке [из п. 6 ГОСТ 19.402-78]
Используемые технические средства
Вызов и загрузка
В разделе «Вызов и загрузка» должны быть указаны:
Допускается указывать адреса загрузки, сведения об использовании оперативной памяти, объем программы [из п. 8 ГОСТ 19.402-78]
Входные данные
В разделе «Входные данные» должны быть указаны:
[из п. 9 ГОСТ 19.402-78]
Выходные данные
В разделе «Выходные данные» должны быть указаны:
[из п. 10 ГОСТ 19.402-78]
Допускается содержание разделов иллюстрировать пояснительными примерами, таблицами, схемами, графиками [из п. 11 ГОСТ 19.402-78]
Приложения
В приложение к описанию программы допускается включать различные материалы, которые нецелесообразно включать в разделы описания [из п. 12 ГОСТ 19.402-78]