Опыт применения ЕСПД

Введение

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

В свое время, когда я только начинал работать программистом, часто приходилось слышать “напиши, пожалуйста, документацию к своей программе”. Я честно все описывал, отдавал начальнику, после чего начинался сеанс черной магии. Начальник через некоторое время меня вызывал и начинал мычать нечленораздельные звуки, мять распечатку моего “самого лучшего” текста в руках, бегая глазами. Общий смысл его мычания заключался в том, что получилось “не то”, “не так”, и “посмотри, как делают другие”. Так как никакого другого ответа из него вытянуть было невозможно, я шел за примерами документов к “другим”. Как правило, это были веселые ребята, смысл речей которых заключался в том, что “вот примеры”, “вообще то по ГОСТу” и “это все никому не нужно”. Так я узнал впервые, что программист может соприкоснуться со страшными ГОСТами.
Поразительно, что среди многих десятков моих коллег, очень неглупых программистов, не было никого, кто бы относился к ГОСТам по другому. Даже те несколько человек, которые их знали и, вроде как, даже умели оформлять документы, относились к ним презрительно-формально. Ситуация, когда даже люди, ответственные за управление разработкой не понимают, зачем нужны ГОСТы и как их применят, встречается на многих предприятиях, сплошь и рядом. Да, были и компании, в которых понимали, чем “Описание программы” отличается от “Описания применения”, но таких было явное меньшинство. В интернете вообще господствует точка зрения, что ГОСТы для программистов — это явный рудимент, и нужны только если “нагибают” под них. Эскизный проект считают “сравнительно честным способом отъемы лишних дензнаков у заказчика”. Вникнуть и разобраться пришлось относительно недавно — в процессе разработки системы управления требованиями, заточенной под отечественную специфику. Документацию которая, разумеется, должна генерировать “по ГОСТу”.

Здесь я хочу сосредоточиться только на одной теме, с которой приходиться иметь дело программисту в отечественных предприятиях, особенно в НИИ — на наборе стандартов ЕСПД. Не считаю себя большим знатоком ЕСПД — есть люди, которые десятки лет по нему работают, и наверняка меня поправят. Статья скорее пытается набросать контуры «дорожной карты» для тех, кто только входит в курс дела.

Стандарты

Рассмотрим кратко, какие бывают стандарты (фокусируясь на ИТ-области).

1. международные. Отличительный признак — принят международной организацией. Пример такой организации — ISO (международная организация стандартизации). Пример её стандарта: ISO 2382-12:1988 (Переферийное оборудование). Распространены совместные стандарты ISO и международной электротехнической комиссии(IEC, в по русски — МЭК): например, ISO/IEC 12207:2008 (жизненный цикл ПО);
2. региональные. Отличительный признак — принят региональной комиссией по стандартизации. К примеру, многие советские ГОСТы сейчас являются региональным стандартом, т.к. приняты межгосударственным советом, куда входят некоторые бывшие советские республики. Этим советом принимаются и новые стандарты — и они тоже получают обозначение ГОСТ. Пример: ГОСТ 12.4.240-2013;
3. стандарты общественных объединений; К примеру, той же МЭК: IEC 60255;
4. национальные стандарты. Для России в начале таких стандартов — “ГОСТ Р”. Могут быть трех типов:
   1. точные копии международных или региональных. Обозначаются неотличимо от “самописных” (национальных, написанных самостоятельно);
   2. копии международных или региональных с дополнениями. Обозначаются добавлением к шифру отечественного стандарта шифра международного, который был взят за основу. Например: ГОСТ Р ИСО/МЭК 12207;
   3. собственно, национальные стандарты. Например, ГОСТ Р 34.11-94.

Системы обозначений на каждом уровне и в каждой организации свои, для каждого случая придется разбираться отдельно. Чтобы быстро понять, “чей” стандарт перед глазами, можно использовать шпаргалку.

ГОСТ

Итак: стандарты бывают международные, межгосударственные(региональные) и национальные. ГОСТ, как мы выяснили, это региональный стандарт. ГОСТы имеют достаточно запутанную, на мой взгляд, систему обозначений. Полностью она изложена в ГОСТ Р 1.5-2004, я приведу минимум, что бы в ней ориентироваться. Во первых, надо различать обозначение ГОСТа и его классификацию. Обозначение — это, грубо говоря, уникальный идентификатор стандарта. Код по классификатору — это вспомогательный код, помогающий найти стандарт или определить, к какой области знаний он относиться. Классификаторов может быть много, в основном используются два: КГС (классификатор государственных стандартов) и его наследник ОКС (общероссийский классификатор стандартов). Например: “ГОСТ Р 50628—2000“ — это обозначение стандарта.По обозначению понятно только то, что он принят в 2000 году. Он имеет код по ОКС “33.100;35.160”: т.е. “33” — раздел “Телекоммуникации, аудио, видео”, “100” — подраздел “электромагнитная совместимость”. Однако он также входит в ветвь классификатора 35.160. “35” — “Информационные технологии. Машины конторские”, “160” — “Микропроцессорные системы....”. А по КГС он имеет код “Э02”, что означает “Э” — “Электронная техника, радиоэлектроника и связь”, “0” — “Общие правила и нормы по электронной технике, радиоэлектронике и связи”, и т.д.

Если известно обозначение стандарта, то получить его коды по КГС и ОКС можно, к примеру, на вот этом толковом сайте.
Итак, вернемся к обозначениям ГОСТов. Их может быть два варианта:

1. стандарт относиться к серии стандартов. В этом случае после индекса категории стандарта (например, ГОСТ, ГОСТ Р или ГОСТ РВ) идет код серии, точка и обозначение стандарта внутри серии. Правила обозначения стандартов внутри серии устанавливаются правилами серии. Например: ГОСТ РВ 15.201-2000, ГОСТ Р 22.8.0-99, ГОСТ 19.101-77;
2. стандарт не относиться к серии стандартов. Тогда после индекса категории идет просто порядковый номер стандарта, тире и год принятия. Например, ГОСТ Р 50628—2000.

Итак, если совсем просто — то обозначение ГОСТа — это либо просто порядковый номер, тире, год, либо номер серии, точка и дальше в зависимости от серии. В реальности все сложнее ( к примеру, можно встретить что то типа ГОСТ 11326.19-79, и это будет вовсе не серия 11326 — но программистам такое нужно очень редко. За подробностями — в ГОСТ Р 1.5-2004).

ЕСПД

ЕСПД — одна из таких серий ГОСТов, номер 19. Т.е. все стандарты, относящиеся к ЕСПД, начинаются с префикса “19.”: например, ГОСТ 19.106-78. Расшифровывается как “Единая система программной документации”. Существуют и другие серии:

• ГОСТ ЕСКД (единая система конструкторской документации, префикс “2.”);
• ГОСТ ЕСТД (единая система технологической документации, префикс “3.”);
• ГОСТ Р, Система разработки и постановки продукции на производство, префикс “15.”;
• ГОСТ РВ, Вооружение и военная техника. Система разработки и постановки продукции на производство, префикс “15.”;
• ГОСТ, Система технической документации на АСУ, префикс “24.”;
• ГОСТ, Комплекс стандартов на автоматизированные системы, префикс “34.”.

Итак, ЕСПД содержит в себе набор стандартов, применяемых при разработке программного обеспечения. Далее для каждого стандарта из ЕСПД дается краткая характеристика и пояснение для неочевидных случаев.

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. Общие требования к программным документам, выполненным печатным способом

Самый объемный стандарт из ЕСПД, уступающий разве что описанию R-схем. Является основным рабочим стандартом при оформлении документации. Вводит правила оформления текста, элементов структуры документа, изображений, формул и т.д. Однако в отличии от соответствующего 2.106 из ЕСКД, 19.106 существенно менее подробный, что приводит к многочисленным неопределенностям.
Во первых, стандарт фактически не определяет межстрочное расстояние и величину вертикальных отступов между заголовками. Он вводит три правила определения интервала: для машинописного текста, машинного и типографского.
Машинописный текст — это текст, набранный на печатной машинке. Смещение следующей строки относительно предыдущей производилось автоматически при так называемом «переводе каретки» — переходе к печати следующей строки, производимым перемещением специального рычага. Как правило, интервал мог быть вручную скорректирован поворотом вала протяжки бумаги, и имел “настройку”, позволяющую задать величину интервала — одинарный или двойной.
Машинный — это, скорее всего, и есть распечатанный текст. Но для него есть только указание, что результат должен быть пригоден для микрофильмирования. Это неявная ссылка на 13.1.002-2003, в котором, к сожалению, задается межстрочный интервал (и, кстати, минимальная высота шрифта) только для рукописных документов (п.4.2.5).
Типографский — текст, набранный в типографии. Учитывая год принятия стандарта, скорее всего речь идет о
[высокой печати, где межстрочный интервал определялся используемыми литерами. Я не специалист в типографском деле, а информации о методах набора сейчас очень мало.
Какой интервал использовать в итоге часто определяется местным нормоконтролем или СТО. Типичные значения — полуторный интервал и 14 размер шрифта.
Часто вызывает много вопросов способ структурирования документа. 19.106 считает, что весь документ делится на разделы, подразделы, пункты и подпункты. У всех них (кроме раздела и подраздела) заголовок может быть и или не быть. При этом:

• “в содержание документа включают номер разделов, подразделов, пунктов и подпунктов, имеющих заголовок” (п. 2.1.4). Это прямое указание на то, что подпункт может иметь заголовок и включаться в оглавление;
• “допускается помещать текст между заголовками раздела и подраздела, между заголовками подраздела и пункта”. Важно обратить внимание, что ненумерованный текст может быть только между заголовками, и только на верхних 2х уровнях.

В отличии от ЕСКД, в ЕСПД принят странный способ оформления рисунков: сначала идет название рисунка, потом сам рисунок, потом опциональный “подрисуночный текст”, и потом, на новой строке, “Рис. N”.
Этот стандарт имеет ряд “дыр”, недостказанностей. К примеру, сказано: “иллюстрации, если их в данном документе более одной, нумеруют арабскими цифрами в пределах всего документа. “ Но если иллюстрация одна, то она ненумерованная, и как тогда на нее ссылаться? Аналогично и для таблиц. Для сносок ГОСТ не указывает способ их нумерации — в пределах всего документа или в пределах страницы.
Таблицы. В самом документе дана ссылка на ГОСТ 1.5.68. Судя по первой серии, несложно заключить, что это стандарт на разработку стандартов. Причем тут он, неясно. По смыслу он соответствует правилам оформления таблиц в ЕСКД, с небольшими исключениями. Этот стандарт был отменен, взамен веден, через несколько итераций, 1.5-2012, в котором правила оформления таблицы… просто исчезли. Еще в 1.5-2002 были, а уже в 1.5-2004 исчезли. В реальной жизни мы оформляем таблицы согласно ЕСКД.
Приложения. Стандарт не указывает, попадают ли рисунки, формулы и таблицы из приложений в общий перечень. Аналогично не сказано, нужно ли в оглавлении раскрывать структуру приложения, если оно содержит свои разделы, пункты и т.д. В нашей практике мы не раскрываем внутренности приложений.
Наконец, следует сказать об отступах. Абзацный отступ, равный 5 символам, является общим для:

• красной строки;
• отступа элемента структуры документа после раздела (подраздел, пункт, подпункт);
• элемент перечисления.

При этом текст, расположенный на следующей строку после строки с отступом, выравнивается уже по левому полю. Часто встречаются ошибки, когда отступ скачет — красная строка — одно значение, номер пункта — нас другим интервалом, в вложенные отступы в списках — так вообще обязательно.

В следующих частях планирую уже добраться до конца списка стандартов ЕСПД.

Автор: KirillAlexandrovich

Источник