ГОСТ Стандарт документирования программного обеспечения
Единая система документации программной продукции – ЕСПД – относится к ГОСТ класса 19 и подразделяется на 10 групп:
1. Основополагающие стандарты.
2. Правила выполнения документации разработки.
3. Правила выполнения документации изготовления.
4. Правила выполнения документации сопровождения.
5. Правила выполнения эксплуатационной документации.
6. Правила обращения программной документации.
Стандарт с номером 0 содержит общие положения, стандарты 7 и 8 являются зарезервированными и к номеру 9 относятся прочие стандарты, не вошедшие в первые 6.
Это краткие описания ГОСТов класса 19, для более подробного ознакомления с ними необходимо обратиться к справочникам.
Перечень документации, декларируемой ГОСТ 19.105-78:
1. Документы, содержащие сведения, необходимые для разработки программного продукта, его изготовления.
1.1. Спецификация – состав программы и документации на нее.
1.2. Ведомость держателей подлинников – перечень предприятий, на которых хранятся подлинники программной документации.
1.3. Текст программы – запись текста программы с необходимыми комментариями.
1.4. Описание программы – сведения о логической и функциональной структуре программы.
1.5. Программа и методика испытаний – требования, подлежащие проверке при испытании программы, порядок и методы их контроля.
1.6. Техническое задание – назначение и область применения программы, технические и специальные требования, необходимые стадии и сроки разработки, виды испытаний.
1.7. Пояснительная записка – схема алгоритма, общее описания алгоритма, выполняемая программой функция. Объяснение принятых технических решений.
2. Документы, используемые при эксплуатации программного продукта.
Ведомость эксплуатационных документов – перечень эксплуатационных документов на программу.
Формуляр – основные характеристики программы, комплектность, общие сведения об эксплуатации программы.
Описание применения – сведения о назначении программы, области применения, классе решаемых задач, ограничения на применение, необходимая конфигурация технических средств.
Руководство системного программиста – сведения для проверки и обеспечения функциональности, настройки программы.
Руководство программиста – сведения для эксплуатации настроенной программы.
Руководство оператора – сведения для обеспечения процедуры общения оператора с ЭВМ в процессе выполнения программы.
Описание языка – описание синтаксиса и семантики языка, используемого в программе.
Руководство по техническому обслуживанию – сведения для применения тестовых программ при обслуживании технических средств.
Другие ГОСТы класса 19:
Полное меню
Основные ссылки
Вернуться в «Каталог СНиП»
ГОСТ 19.106-78* Единая система программной документации. Требования к программным документам, выполненным печатным способом.
ГОСУДАРСТВЕННЫЙ СТАНДАРТ СОЮЗА ССР
ЕДИНАЯ СИСТЕМА ПРОГРАММНОЙ ДОКУМЕНТАЦИИ
ТРЕБОВАНИЯ К ПРОГРАММНЫМ ДОКУМЕНТАМ,
ВЫПОЛНЕННЫМ ПЕЧАТНЫМ СПОСОБОМ
ГОСУДАРСТВЕННЫЙ СТАНДАРТ СОЮЗА ССР
Единая система программной документации
ТРЕБОВАНИЯ К ПРОГРАММНЫМ ДОКУМЕНТАМ,
ВЫПОЛНЕННЫМ ПЕЧАТНЫМ СПОСОБОМ
Постановлением Государственного комитета СССР по стандартам от 18 декабря 1978 г. № 3350 срок введения установлен
* Переиздание (Ноябрь 1987 г.) с Изменением №1, утвержденным в сентябре 1981г. (ИУС 11-81).
Настоящий стандарт устанавливает правила выполнения программных документов для вычислительных машин, комплексов и систем независимо от их назначения и области применения и предусмотренных стандартами Единой системы программной документации (ЕСПД) для печатного способа выполнения.
Стандарт не распространяется на программный документ «Текст программы».
Стандарт соответствует СТ СЭВ 2088-80 в части установления структуры и требований к изложению программных документов (см. справочное приложение 1).
1. ОБЩИЕ ТРЕБОВАНИЯ
1.1. Состав и структура программного документа устанавливаются по ГОСТ 19.105-78.
1. При выполнении программного документа допускается сочетание печатных способов, указанных в п. 1.2 настоящего стандарта.
1.3. Вписывать в программные документы, выполненные машинописным, машинным и рукописным способами, отдельные слова, формулы, условные знаки ( o т руки чертежным шрифтом), буквы латинского и греческого алфавитов, а также выполнять схемы и рисунки необходимо черными чернилами или тушью.
1.4. При машинописном, машинном и рукописном способах выполнения документа опечатки и графические неточности, обнаруженные в процессе выполнения, допускается исправлять подчисткой некачественно выполненной части текста (чертежа) и нанесением на том же листе исправленного текста (графики) машинописью или черной тушью в зависимости от способа выполнения документа.
Повреждения листов документов, помарки и следы не полностью удаленного прежнего текста (графики) не допускаются.
1.5. Программные документы оформляют:
на листах типографских форматов при изготовлении документа типографским способом.
1.6. Материалы программного документа располагают в следующей последовательности:
лист утверждения (не входит в общее количество листов документа);
титульный лист (первый лист документа);
текст документа (с рисунками, таблицами и т. п.);
перечень ссылочных документов;
перечень символов и числовых коэффициентов;
часть регистрации изменений;
лист регистрации изменений.
Приложения, перечни терминов, сокращений, рисунков и таблиц, предметный указатель, перечни ссылочных документов, символов и числовых коэффициентов выполняются при необходимости.
(Измененная редакция, Изм. № 1).
1.7. Перечни терминов и сокращений, предметный указатель, перечень символов и числовых коэффициентов следует составлять в алфавитном порядке.
Остальные перечни редакция составляют в порядке возрастания номеров.
(Введен дополнительно, Изм. № 1).
2.1. Построение документа
2.1.1. При необходимости допускается делить документ на части. Деление на части осуществляется на уровне не ниже раздела. Каждую часть комплектуют отдельно. Всем частям присваивают обозначение документа в соответствии с ГОСТ 19.103-77.
Части оформляют в соответствии с требованиями настоящего стандарта, при этом в конце содержания первой части следует перечислять обозначения остальных частей.
Допускается включать в документ части текста программы, оформляемые в соответствии с правилами языка, на котором написан текст программы.
Нумерацию страниц документа, а также нумерацию разделов, рисунков и таблиц производят в пределах каждой части. Каждую часть начинают с титульного листа.
Отдельная нумерация страниц документа в пределах раздела и подраздела не допускается.
Лист утверждения выпускают на весь документ с обозначением первой части.
(Измененная редакция, Изм. № 1).
2.1.2. Информационная и основная части программного документа выполняются по форме 1 или 2, где:
Рамку (границы) формата страниц документа допускается не наносить.
2.1.3. Аннотацию размещают на отдельной (пронумерованной) странице с заголовком «АННОТАЦИЯ» и не нумеруют как раздел.
В аннотации указывают издание программы, кратко излагают назначение и содержание документа. Если документ состоит из нескольких частей, в аннотации указывают общее количество частей.
2.1.4. Содержание документа размещают на отдельной (пронумерованной) странице (страницах) после аннотации, снабжают заголовком «СОДЕРЖАНИЕ», не нумеруют как раздел и включают в общее количество страниц документа.
В содержание документа включают номера разделов, подразделов, пунктов и подпунктов, имеющих заголовок, их наименование и номера страниц; номера и наименование (при наличии) приложений программного документа и номера страниц; прочие наименования (перечень рисунков, таблиц и т.п.) и номера страниц.
Наименования, включенные в содержание, записывают строчными буквами. Прописными должны печататься заглавные буквы и аббревиатуры.
2.1.3, 2.1.4. (Измененная редакция, Изм. № 1).
2.1.6. Структурными элементами текста документа являются разделы, подразделы, пункты, подпункты и перечисления.
При отсутствии разделов в тексте документа его первым структурным элементом является пункт.
Допускается помещать текст между заголовками раздела и подраздела, между заголовками подраздела и пункта.
Внутри подразделов, пунктов и подпунктов могут быть даны перечисления, которые рекомендуется обозначать арабскими цифрами со скобкой: 1), 2) и т.д. Допускается выделять перечисления простановкой дефиса перед текстом.
Не рекомендуется делать ссылки на элементы перечисления.
Каждый структурный элемент начинается с абзацного отступа.
(Измененная редакция, Изм. № 1).
2.1.7. Заголовки разделов пишут прописными буквами и размещают симметрично относительно правой и левой границ текста.
Заголовки подразделов записывают с абзаца строчными буквами (кроме первой прописной).
Допускается при машинном способе выполнения документа заголовки подразделов и пунктов записывать шрифтом, имеющимся на печатающем устройстве.
Переносы слои в заголовках не допускаются. Точку в конце заголовка не ставят.
Если заголовок состоит из двух предложений, их разделяют точкой.
Каждый раздел рекомендуется начинать с нового листа.
(Измененная редакция, Изм. № 1).
Для разделов и подразделов, текст которых записывают на одной странице с текстом предыдущего раздела, расстояние между последней строкой текста и последующим заголовком должно быть равно:
Расстояние между основаниями строк заголовка принимают таким, как в тексте.
При типографском способе издания документов указанные расстояния оформляют по правилам для типографских изданий.
2.1.9. Разделы, подразделы, пункты и подпункты следует нумеровать арабскими цифрами с точкой.
Разделы должны иметь порядковый номер (1, 2 и т.д.).
В пределах раздела должна быть сквозная нумерация по всем подразделам, пунктам и подпунктам, входящим в данный раздел.
Нумерация подразделов включает номер раздела и порядковый номер подраздела, входящего в данный раздел, разделенные точкой (2.1, 3.1 и т.д.).
При наличии разделов и подразделов к номеру подраздела после точки добавляют порядковый номер пункта и подпункта (3.1.1, 3.1.1.1 и т. д.).
Пример структуры текста программного документа и нумерация его разделов, подразделов, пунктов и подпунктов приведен в справочном приложении 2.
(Измененная редакция, Изм. № 1).
2.1.10. (Исключен, Изм. № 1).
2.2. Текст документа
2.2.1. Текст документа должен быть кратким, четким, исключающим возможность неоднозначного толкования.
2.2.2. Допускаются сокращения слов в тексте и надписях под иллюстрациями по ГОСТ 2.316-68. Дополнительные сокращения, принятые в документе и не входящие в ГОСТ 2.316-68, следует приводить в перечне принятых сокращений.
2.2.3. Для выделения отдельных понятий допускается изменять интервалы между словами, а также печатать отдельные слова или части текста шрифтом, отличным от печати основного текста, например:
АВС3091 СИНТАКСИЧЕСКАЯ ОШИБКА
2.2.4. Необходимые пояснения к тексту документа могут оформляться сносками.
Если сноска относится к отдельному слову, знак сноски помещается непосредственно у этого слова, если же к предложению в целом, то в конце предложения. Текст сноски располагают в конце страницы и отделяют от основного текста линией длиной 3 см, проведенной в левой части страницы.
2.3.1. Иллюстрации могут быть расположены в тексте документа и (или) в приложениях.
Иллюстрации, если их в данном документе более одной, нумеруют арабскими цифрами в пределах всего документа.
В приложениях иллюстрации нумеруются в пределах каждого приложения в порядке, установленном для основного текста документ.
Ссылки на иллюстрации дают по типу: «рис. 12» или «(рис. 12)».
Ссылки на ранее упомянутые иллюстрации дают с сокращенным словом «смотри», например, «см. рис.12».
Иллюстрации могут иметь тематический заголовок и под рисуночный текст, поясняющий содержание иллюстрации.
(Измененная редакция, Изм. № 1).
2.4.1. Формулы в документе, если их более одной, нумеруются арабскими цифрами, номер ставят с правой стороны страницы, в скобках, на уровне формулы.
В пределах всего документа или его частей, в случае деления документа на части, формулы имеют сквозную нумерацию.
Ссылки в тексте на порядковый номер формулы дают в скобках, например: «в формуле (3)».
При делении документа на части номер части ставится перед порядковым номером формулы и отделяется от последней точкой, например: «в формуле (1.4)».
2.4.2. Значения символов и числовых коэффициентов, входящих в формулу, должны быть приведены непосредственно под формулой. Значение каждого символа печатают с новой строки в той последовательности, в какой они приведены в формуле. Первая строка расшифровки должна начинаться со слова «где», без двоеточия после него.
Если в программном документе приведен перечень этих символов и числовых коэффициентов, значения их под формулой допускается не приводить.
(Измененная редакция, Изм. № 1).
2.4.3. Размерность одного и того же параметра в пределах одного документа должна быть постоянной.
2.5.1. В программных документах допускаются ссылки на стандарты (кроме стандартов предприятий), технические условия и другие документы (например, документы органов Государственного надзора, правила и нормы Госстроя СССР). При ссылках на стандарты и технические условия указывают их обозначения.
Ссылаться следует на документ в целом или на его разделы и приложения (с указанием обозначения и наименования документа, номера и наименования раздела или приложения). При повторных ссылках на раздел или приложение указывают только номер.
При ссылках на документ допускается проставлять в квадратных скобках его порядковый номер в соответствии с перечнем ссылочных документов.
Допускается указывать только обозначение документа и (или) разделов без указания их наименований. Ссылки на отдельные подразделы, пункты и иллюстрации другого документа не допускаются. Допускаются ссылки внутри документа на пункты, иллюстрации и отдельные подразделы.
(Измененная редакция, Изм. № 1).
2.6.1. Цифровой материал для достижения лучшей наглядности и сравнимости показателей, как правило, следует оформлять в виде таблицы.
2.6.2. Оформление таблиц должно производиться в соответствии с требованиями ГОСТ 1.5-85.
Таблица может иметь заголовок, который следует выполнять строчными буквами. Прописными должны печататься заглавные буквы и аббревиатуры.
(Измененная редакция, Изм. № 1).
2.6.3. Сноски к таблицам располагают непосредственно под таблицей, например:
Наборы данных, используемые для распечатки
Опыт применения ЕСПД
Введение
Основная задача этого текста — рассказать, что такое Единая система программной документации (ЕСПД) и как эти стандарты применять на практике. Начну с рассказа о том, какие бывают стандарты, и закончу опытом применения каждого из ЕСПДшных стандартов в отдельности.
В свое время, когда я только начинал работать программистом, часто приходилось слышать “напиши, пожалуйста, документацию к своей программе”. Я честно все описывал, отдавал начальнику, после чего начинался сеанс черной магии. Начальник через некоторое время меня вызывал и начинал мычать нечленораздельные звуки, мять распечатку моего “самого лучшего” текста в руках, бегая глазами. Общий смысл его мычания заключался в том, что получилось “не то”, “не так”, и “посмотри, как делают другие”. Так как никакого другого ответа из него вытянуть было невозможно, я шел за примерами документов к “другим”. Как правило, это были веселые ребята, смысл речей которых заключался в том, что “вот примеры”, “вообще то по ГОСТу” и “это все никому не нужно”. Так я узнал впервые, что программист может соприкоснуться со страшными ГОСТами.
Поразительно, что среди многих десятков моих коллег, очень неглупых программистов, не было никого, кто бы относился к ГОСТам по другому. Даже те несколько человек, которые их знали и, вроде как, даже умели оформлять документы, относились к ним презрительно-формально. Ситуация, когда даже люди, ответственные за управление разработкой не понимают, зачем нужны ГОСТы и как их применят, встречается на многих предприятиях, сплошь и рядом. Да, были и компании, в которых понимали, чем “Описание программы” отличается от “Описания применения”, но таких было явное меньшинство. В интернете вообще господствует точка зрения, что ГОСТы для программистов — это явный рудимент, и нужны только если “нагибают” под них. Эскизный проект считают “сравнительно честным способом отъемы лишних дензнаков у заказчика”. Вникнуть и разобраться пришлось относительно недавно — в процессе разработки системы управления требованиями, заточенной под отечественную специфику. Документацию которая, разумеется, должна генерировать “по ГОСТу”.
Здесь я хочу сосредоточиться только на одной теме, с которой приходиться иметь дело программисту в отечественных предприятиях, особенно в НИИ — на наборе стандартов ЕСПД. Не считаю себя большим знатоком ЕСПД — есть люди, которые десятки лет по нему работают, и наверняка меня поправят. Статья скорее пытается набросать контуры «дорожной карты» для тех, кто только входит в курс дела.
Стандарты
Системы обозначений на каждом уровне и в каждой организации свои, для каждого случая придется разбираться отдельно. Чтобы быстро понять, “чей” стандарт перед глазами, можно использовать шпаргалку.
Итак: стандарты бывают международные, межгосударственные(региональные) и национальные. ГОСТ, как мы выяснили, это региональный стандарт. ГОСТы имеют достаточно запутанную, на мой взгляд, систему обозначений. Полностью она изложена в ГОСТ Р 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. Общие требования к программным документам, выполненным печатным способом
В следующих частях планирую уже добраться до конца списка стандартов ЕСПД.
