[Из песочницы] Опыт применения ЕСПД
Введение Основная задача этого текста — рассказать, что такое Единая система программной документации (ЕСПД) и как эти стандарты применять на практике. Начну с рассказа о том, какие бывают стандарты, и закончу опытом применения каждого из ЕСПДшных стандартов в отдельности.В свое время, когда я только начинал работать программистом, часто приходилось слышать «напиши, пожалуйста, документацию к своей программе». Я честно все описывал, отдавал начальнику, после чего начинался сеанс черной магии. Начальник через некоторое время меня вызывал и начинал мычать нечленораздельные звуки, мять распечатку моего «самого лучшего» текста в руках, бегая глазами. Общий смысл его мычания заключался в том, что получилось «не то», «не так», и «посмотри, как делают другие». Так как никакого другого ответа из него вытянуть было невозможно, я шел за примерами документов к «другим». Как правило, это были веселые ребята, смысл речей которых заключался в том, что «вот примеры», «вообще то по ГОСТу» и «это все никому не нужно». Так я узнал впервые, что программист может соприкоснуться со страшными ГОСТами.Поразительно, что среди многих десятков моих коллег, очень неглупых программистов, не было никого, кто бы относился к ГОСТам по другому. Даже те несколько человек, которые их знали и, вроде как, даже умели оформлять документы, относились к ним презрительно-формально. Ситуация, когда даже люди, ответственные за управление разработкой не понимают, зачем нужны ГОСТы и как их применят, встречается на многих предприятиях, сплошь и рядом. Да, были и компании, в которых понимали, чем «Описание программы» отличается от «Описания применения», но таких было явное меньшинство. В интернете вообще господствует точка зрения, что ГОСТы для программистов — это явный рудимент, и нужны только если «нагибают» под них. Эскизный проект считают «сравнительно честным способом отъемы лишних дензнаков у заказчика». Вникнуть и разобраться пришлось относительно недавно — в процессе разработки системы управления требованиями, заточенной под отечественную специфику. Документацию которая, разумеется, должна генерировать «по ГОСТу».Здесь я хочу сосредоточиться только на одной теме, с которой приходиться иметь дело программисту в отечественных предприятиях, особенно в НИИ — на наборе стандартов ЕСПД. Не считаю себя большим знатоком ЕСПД — есть люди, которые десятки лет по нему работают, и наверняка меня поправят. Статья скорее пытается набросать контуры «дорожной карты» для тех, кто только входит в курс дела.
Стандарты Рассмотрим кратко, какие бывают стандарты (фокусируясь на ИТ-области).международные. Отличительный признак — принят международной организацией. Пример такой организации — ISO (международная организация стандартизации). Пример её стандарта: ISO 2382–12:1988 (Переферийное оборудование). Распространены совместные стандарты ISO и международной электротехнической комиссии (IEC, в по русски — МЭК): например, ISO/IEC 12207:2008 (жизненный цикл ПО); региональные. Отличительный признак — принят региональной комиссией по стандартизации. К примеру, многие советские ГОСТы сейчас являются региональным стандартом, т.к. приняты межгосударственным советом, куда входят некоторые бывшие советские республики. Этим советом принимаются и новые стандарты — и они тоже получают обозначение ГОСТ. Пример: ГОСТ 12.4.240–2013; стандарты общественных объединений; К примеру, той же МЭК: IEC 60255; национальные стандарты. Для России в начале таких стандартов — «ГОСТ Р». Могут быть трех типов: точные копии международных или региональных. Обозначаются неотличимо от «самописных» (национальных, написанных самостоятельно); копии международных или региональных с дополнениями. Обозначаются добавлением к шифру отечественного стандарта шифра международного, который был взят за основу. Например: ГОСТ Р ИСО/МЭК 12207; собственно, национальные стандарты. Например, ГОСТ Р 34.11–94. Системы обозначений на каждом уровне и в каждой организации свои, для каждого случая придется разбираться отдельно. Чтобы быстро понять, «чей» стандарт перед глазами, можно использовать шпаргалку.
ГОСТ Итак: стандарты бывают международные, межгосударственные (региональные) и национальные. ГОСТ, как мы выяснили, это региональный стандарт. ГОСТы имеют достаточно запутанную, на мой взгляд, систему обозначений. Полностью она изложена в ГОСТ Р 1.5–2004, я приведу минимум, что бы в ней ориентироваться. Во первых, надо различать обозначение ГОСТа и его классификацию. Обозначение — это, грубо говоря, уникальный идентификатор стандарта. Код по классификатору — это вспомогательный код, помогающий найти стандарт или определить, к какой области знаний он относиться. Классификаторов может быть много, в основном используются два: КГС (классификатор государственных стандартов) и его наследник ОКС (общероссийский классификатор стандартов). Например: «ГОСТ Р 50628—2000» — это обозначение стандарта.По обозначению понятно только то, что он принят в 2000 году. Он имеет код по ОКС »33.100;35.160»: т.е.»33» — раздел «Телекоммуникации, аудио, видео»,»100» — подраздел «электромагнитная совместимость». Однако он также входит в ветвь классификатора 35.160.»35» — «Информационные технологии. Машины конторские»,»160» — «Микропроцессорные системы…». А по КГС он имеет код «Э02», что означает «Э» — «Электронная техника, радиоэлектроника и связь»,»0» — «Общие правила и нормы по электронной технике, радиоэлектронике и связи», и т.д. Если известно обозначение стандарта, то получить его коды по КГС и ОКС можно, к примеру, на вот этом толковом сайте.Итак, вернемся к обозначениям ГОСТов. Их может быть два варианта:
стандарт относиться к серии стандартов. В этом случае после индекса категории стандарта (например, ГОСТ, ГОСТ Р или ГОСТ РВ) идет код серии, точка и обозначение стандарта внутри серии. Правила обозначения стандартов внутри серии устанавливаются правилами серии. Например: ГОСТ РВ 15.201–2000, ГОСТ Р 22.8.0–99, ГОСТ 19.101–77; стандарт не относиться к серии стандартов. Тогда после индекса категории идет просто порядковый номер стандарта, тире и год принятия. Например, ГОСТ Р 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 символам, является общим для:
