- PVSM.RU - https://www.pvsm.ru -
Основная задача этого текста — рассказать, что такое Единая система программной документации (ЕСПД) и как эти стандарты применять на практике. Начну с рассказа о том, какие бывают стандарты, и закончу опытом применения каждого из ЕСПДшных стандартов в отдельности.
В свое время, когда я только начинал работать программистом, часто приходилось слышать “напиши, пожалуйста, документацию к своей программе”. Я честно все описывал, отдавал начальнику, после чего начинался сеанс черной магии. Начальник через некоторое время меня вызывал и начинал мычать нечленораздельные звуки, мять распечатку моего “самого лучшего” текста в руках, бегая глазами. Общий смысл его мычания заключался в том, что получилось “не то”, “не так”, и “посмотри, как делают другие”. Так как никакого другого ответа из него вытянуть было невозможно, я шел за примерами документов к “другим”. Как правило, это были веселые ребята, смысл речей которых заключался в том, что “вот примеры”, “вообще то по ГОСТу” и “это все никому не нужно”. Так я узнал впервые, что программист может соприкоснуться со страшными ГОСТами.
Поразительно, что среди многих десятков моих коллег, очень неглупых программистов, не было никого, кто бы относился к ГОСТам по другому. Даже те несколько человек, которые их знали и, вроде как, даже умели оформлять документы, относились к ним презрительно-формально. Ситуация, когда даже люди, ответственные за управление разработкой не понимают, зачем нужны ГОСТы и как их применят, встречается на многих предприятиях, сплошь и рядом. Да, были и компании, в которых понимали, чем “Описание программы” отличается от “Описания применения”, но таких было явное меньшинство. В интернете вообще господствует точка зрения, что ГОСТы для программистов — это явный рудимент, и нужны только если “нагибают” под них. Эскизный проект считают “сравнительно честным способом отъемы лишних дензнаков у заказчика”. Вникнуть и разобраться пришлось относительно недавно — в процессе разработки системы управления требованиями, заточенной под отечественную специфику. Документацию которая, разумеется, должна генерировать “по ГОСТу”.
Здесь я хочу сосредоточиться только на одной теме, с которой приходиться иметь дело программисту в отечественных предприятиях, особенно в НИИ — на наборе стандартов ЕСПД. Не считаю себя большим знатоком ЕСПД — есть люди, которые десятки лет по нему работают, и наверняка меня поправят. Статья скорее пытается набросать контуры «дорожной карты» для тех, кто только входит в курс дела.
Рассмотрим кратко, какие бывают стандарты (фокусируясь на ИТ-области).
Системы обозначений на каждом уровне и в каждой организации свои, для каждого случая придется разбираться отдельно. Чтобы быстро понять, “чей” стандарт перед глазами, можно использовать шпаргалку [1].
Итак: стандарты бывают международные, межгосударственные(региональные) и национальные. ГОСТ, как мы выяснили, это региональный стандарт. ГОСТы имеют достаточно запутанную, на мой взгляд, систему обозначений. Полностью она изложена в ГОСТ Р 1.5-2004, я приведу минимум, что бы в ней ориентироваться. Во первых, надо различать обозначение ГОСТа и его классификацию. Обозначение — это, грубо говоря, уникальный идентификатор стандарта. Код по классификатору — это вспомогательный код, помогающий найти стандарт или определить, к какой области знаний он относиться. Классификаторов может быть много, в основном используются два: КГС (классификатор государственных стандартов) и его наследник ОКС (общероссийский классификатор стандартов). Например: “ГОСТ Р 50628—2000“ — это обозначение стандарта.По обозначению понятно только то, что он принят в 2000 году. Он имеет код по ОКС “33.100;35.160”: т.е. “33” — раздел “Телекоммуникации, аудио, видео”, “100” — подраздел “электромагнитная совместимость”. Однако он также входит в ветвь классификатора 35.160. “35” — “Информационные технологии. Машины конторские”, “160” — “Микропроцессорные системы....”. А по КГС он имеет код “Э02”, что означает “Э” — “Электронная техника, радиоэлектроника и связь”, “0” — “Общие правила и нормы по электронной технике, радиоэлектронике и связи”, и т.д.
Если известно обозначение стандарта, то получить его коды по КГС и ОКС можно, к примеру, на вот этом толковом сайте [2].
Итак, вернемся к обозначениям ГОСТов. Их может быть два варианта:
Итак, если совсем просто — то обозначение ГОСТа — это либо просто порядковый номер, тире, год, либо номер серии, точка и дальше в зависимости от серии. В реальности все сложнее ( к примеру, можно встретить что то типа ГОСТ 11326.19-79, и это будет вовсе не серия 11326 — но программистам такое нужно очень редко. За подробностями — в ГОСТ Р 1.5-2004).
ЕСПД — одна из таких серий ГОСТов, номер 19. Т.е. все стандарты, относящиеся к ЕСПД, начинаются с префикса “19.”: например, ГОСТ 19.106-78. Расшифровывается как “Единая система программной документации”. Существуют и другие серии:
Итак, ЕСПД содержит в себе набор стандартов, применяемых при разработке программного обеспечения. Далее для каждого стандарта из ЕСПД дается краткая характеристика и пояснение для неочевидных случаев.
Описывает правила присвоения обозначений стандартов в серии ЕСПД. В практической жизни не нужен.
Описывает правила построения и оформления алгоритмов. Использует обозначения из 19.103. В моей практике был нужен единственный раз, когда при сертификационная лаборатория уперлась по формальному признаку, что нужна именно схема алгоритма. С моей точки зрения, классические блок-схемы двумя ногами в прошлом, и единственно, где остались более-менее уместными, это если при изложении автор хочет акцентировать внимание читателя именно на алгоритме.
Приведены графические обозначения допустимых типов элементов блок-схемы. Нужен, если используются блок-схемы.
Скудный глоссарий. Из интересного — содержит формальные определения программного и эксплуатационного документов.
Практически забытый язык. В свое время Р-схемы широко использовались в ракетно-космической отрасли, став стандартом де-факто для написания программ управления пусками и моделирования запусков. Однако ныне этот язык полностью предан забвению. В своей работе я ни разу не сталкивался с Р-схемами. Хотя по сравнению с блок-схемами они имеют заметные преимущества: компактны, подходят для визуализации нелинейных алгоритмов (например, классов в С++) или структур данных. При этом в интернете информации по ним практически нет: мне показались полезными вот этот [3] и вот этот [4] сайты. В любом случае, если бы сейчас мне пришлось вставлять в программную документацию схему алгоритма, я бы выбрал Р-схемы, а не блок-схемы.
Содержит таблицу соответствия вида документа его коду, а также деление видов документов на эксплуатационные и программные. Вводится понятие комплекса и компонента. Больше ничего полезного нет.
Важный и нужный стандарт, в котором описаны виды документов и приведены коды видов программных документов. Этот стандарт (совместно с 19.103-77) является одним из ключей к “разгадке” обозначений документов подобных АБВГ.10473-01 32 01-1.
В стандарте вводится понятие комплекса и компонента (на ряде предприятий добавляют третий вид — комплект, когда речь идет о несвязанных программных элементах), дается разделение: какие документы эксплуатационные, какие нет.
Следует аккуратно относиться к таблице 4, в которой показано, какой документ на какой стадии разработки выполняется. Стадии разработки обычно регламентируются в стандартах на выполнения ОКР, и там-же указывается, какие документы нужно предъявлять заказчику на каждом этапе.
На моей памяти этот стандарт не применялся ни разу: кто что делает на каком этапе и чем отчитывается прописывается в ТТЗ или делается отсылка к ГОСТам, где это прописано более четко (например, ГОСТ РВ 15.203). При этом для новичка он содержит неплохой в своей лаконичности конспект работ на основных этапах ОКР.
Нужен, в основном, для того, что бы научиться читать обозначения документов подобных приведенному выше. Однако понимание схемы обозначений полезно в случае, когда приходиться выходить за рамки типовых работ: к примеру, помнить, что документы с кодами после 90 — пользовательские, т.е. любые. В моей практике мы выпускали документ 93, который назвали “Ведомость программной документации”, 96 документ — “Инструкция по сборке”.
Распространенное словосочетание “вариант исполнения” в ЕСПД отсутствует, и заменяется “номером редакции”. С одной стороны, это не совсем корректно: номер редакции задумывался для отслеживания эволюции программы: вначале выходит первая редакция, потом, к примеру, после доработки — вторая. Но на практике, когда нужно выпустить версию ПО для нескольких операционных систем (кросс-платформенное ПО), другого выхода нет. Точнее — есть, но неправильный: присвоить версии для каждой операционки свое обозначение — и закладывать в архив несколько дисков с исходниками (по числу операционок), разрабатывать (фактически — копировать) весь комплект документации и т.д… Т.е. чистой воды бестолковая и сбивающая с толку деятельность. Решение в виде присвоения версии под каждую операционку своего номера редакции позволяет часть документов сделать общими.
В ЕСПД используется смущающее многих программистов обозначение исходных текстов программы и результата сборки “документами”. Документ “текст программы”, согласно 19.101-77, имеет обозначение 12. Дальше принято, что исходники обозначаются как 12 01 — т.е. 01(первый) документ вида 12, а бинарники — как 12 02 — т.е. второй документ вида 12. В ряде случаев для сборки программы требуются дополнительные инструментальные средства — компиляторы, генераторы инсталляторов и т.д. Т.е. программы, которые не входят в поставку, но нужны для сборки. Решением может быть их обозначение как 12 03 — т.е. третий документ вида 12.
Описывает два листа документа — лист утверждения (ЛУ) и титульный лист. Лист утверждения в ЕСПД содержит подписи как начальства, утвердившего документ, так и разработчиков, нормоконтролеров, представителей приемки и т.д. Т.е. на нем присутствует достаточно много чувствительной для предприятия информации. Поэтому в стандарте принято, что ЛУ остается на предприятии-разработчике, и высылается только по особому указанию. Еще раз — ЛУ не является частью документа, а является как бы отдельным документом, и в спецификацию его вносят отдельной строкой.
Поначалу смущающая странность в отделении ЛУ от самого документа имеет весьма веские причины:
Что касается оформления ЛУ, то сплошь и рядом на предприятиях используется смесь — часть надписей ЛУ оформляется по ЕСПД, часть — по ЕСКД, а часть — по своему. Поэтому лучше всего прежде, чем делать ЛУ самому, поискать, нет ли стандарта предприятия (СТО), или взять пример у местного нормоконтроля.
Также следует помнить, что ЛУ не нумеруется, и первый лист — титульный, а первый лист, на котором ставится номер — следующий за титульным. Но в том случае, если ЛУ больше одного (это бывает, если все подписи не влезли на лист), то ЛУ нумеруются отдельно.
Вводится общая структура документа, не зависящая от способа его исполнения. Т.е. еще в 1978 году было заложено в стандарт, что документ может быть не обязательно бумажным. В частности, вводиться понятие содержания для полностью электронных документов. Для бумажного исполнения, распространенного в то время, был принят ГОСТ 19.106-78.
В настоящее время к этому стандарту приходиться обращаться очень редко: разве что забывается порядок следования основных частей документа.
Самый объемный стандарт из ЕСПД, уступающий разве что описанию R-схем. Является основным рабочим стандартом при оформлении документации. Вводит правила оформления текста, элементов структуры документа, изображений, формул и т.д. Однако в отличии от соответствующего 2.106 из ЕСКД, 19.106 существенно менее подробный, что приводит к многочисленным неопределенностям.
Во первых, стандарт фактически не определяет межстрочное расстояние и величину вертикальных отступов между заголовками. Он вводит три правила определения интервала: для машинописного текста, машинного и типографского.
Машинописный текст — это текст, набранный на печатной машинке. Смещение следующей строки относительно предыдущей производилось автоматически при так называемом «переводе каретки» — переходе к печати следующей строки, производимым перемещением специального рычага. Как правило, интервал мог быть вручную скорректирован поворотом вала протяжки бумаги, и имел “настройку”, позволяющую задать величину интервала — одинарный или двойной.
Машинный — это, скорее всего, и есть распечатанный текст. Но для него есть только указание, что результат должен быть пригоден для микрофильмирования. Это неявная ссылка на 13.1.002-2003, в котором, к сожалению, задается межстрочный интервал (и, кстати, минимальная высота шрифта) только для рукописных документов (п.4.2.5).
Типографский — текст, набранный в типографии. Учитывая год принятия стандарта, скорее всего речь идет о
[высокой печати [5], где межстрочный интервал определялся используемыми литерами. Я не специалист в типографском деле, а информации о методах набора сейчас очень мало.
Какой интервал использовать в итоге часто определяется местным нормоконтролем или СТО. Типичные значения — полуторный интервал и 14 размер шрифта.
Часто вызывает много вопросов способ структурирования документа. 19.106 считает, что весь документ делится на разделы, подразделы, пункты и подпункты. У всех них (кроме раздела и подраздела) заголовок может быть и или не быть. При этом:
В отличии от ЕСКД, в ЕСПД принят странный способ оформления рисунков: сначала идет название рисунка, потом сам рисунок, потом опциональный “подрисуночный текст”, и потом, на новой строке, “Рис. N”.
Этот стандарт имеет ряд “дыр”, недостказанностей. К примеру, сказано: “иллюстрации, если их в данном документе более одной, нумеруют арабскими цифрами в пределах всего документа. “ Но если иллюстрация одна, то она ненумерованная, и как тогда на нее ссылаться? Аналогично и для таблиц. Для сносок ГОСТ не указывает способ их нумерации — в пределах всего документа или в пределах страницы.
Таблицы. В самом документе дана ссылка на ГОСТ 1.5.68. Судя по первой серии, несложно заключить, что это стандарт на разработку стандартов. Причем тут он, неясно. По смыслу он соответствует правилам оформления таблиц в ЕСКД, с небольшими исключениями. Этот стандарт был отменен, взамен веден, через несколько итераций, 1.5-2012, в котором правила оформления таблицы… просто исчезли. Еще в 1.5-2002 были, а уже в 1.5-2004 исчезли. В реальной жизни мы оформляем таблицы согласно ЕСКД.
Приложения. Стандарт не указывает, попадают ли рисунки, формулы и таблицы из приложений в общий перечень. Аналогично не сказано, нужно ли в оглавлении раскрывать структуру приложения, если оно содержит свои разделы, пункты и т.д. В нашей практике мы не раскрываем внутренности приложений.
Наконец, следует сказать об отступах. Абзацный отступ, равный 5 символам, является общим для:
При этом текст, расположенный на следующей строку после строки с отступом, выравнивается уже по левому полю. Часто встречаются ошибки, когда отступ скачет — красная строка — одно значение, номер пункта — нас другим интервалом, в вложенные отступы в списках — так вообще обязательно.
В следующих частях планирую уже добраться до конца списка стандартов ЕСПД.
Автор: KirillAlexandrovich
Источник [6]
Сайт-источник PVSM.RU: https://www.pvsm.ru
Путь до страницы источника: https://www.pvsm.ru/it-standarty/58633
Ссылки в тексте:
[1] шпаргалку: http://ru.wikipedia.org/wiki/%D0%A1%D0%BF%D0%B8%D1%81%D0%BE%D0%BA_%D0%BE%D0%B1%D0%BE%D0%B7%D0%BD%D0%B0%D1%87%D0%B5%D0%BD%D0%B8%D0%B9_%D1%81%D1%82%D0%B0%D0%BD%D0%B4%D0%B0%D1%80%D1%82%D0%BE%D0%B2
[2] вот этом толковом сайте: http://www.vniiki.ru/catalog/gost.aspx
[3] вот этот: http://forum.oberoncore.ru/viewtopic.php?f=62&t=4047
[4] вот этот: http://glushkov.org/?page_id=59
[5] высокой печати: http://ru.wikipedia.org/wiki/%D0%92%D1%8B%D1%81%D0%BE%D0%BA%D0%B0%D1%8F_%D0%BF%D0%B5%D1%87%D0%B0%D1%82%D1%8C
[6] Источник: http://habrahabr.ru/post/218735/
Нажмите здесь для печати.