Документирование сложных программных комплексов. Электронное дополнение к учебному пособию «Программная инженерия сложных заказных программных продукт

ществляемое как неотъемлемая часть процесса разработки программного средства.

Обязанности руководителей по организации документирования проекта программного средства

Определение стратегии документирования проекта программного средства

Выбор стандартов и руководств по документированию программного средства

Определение содержания документации разработки – технологической

Определение содержания документации продукции – эксплуатационной

Определение документации управления проектом программного средства

Выбор комплекса стандартизированных форматов документов

Оценка основных ресурсов для реализации документирования проекта

Планирование документирования проекта программного средства

Рис.2.1

51

Во время разработки ПК администрации необходимо оцени-

вать ход работы, возникающие проблемы и развитие процесса документирования. Периодические стандартизированные отчеты, согласно которым проверяется ход работ по графику и представляются планы на следующий период, должны обеспечивать контроль и обзор развития проекта. Этим специалистам необходимы средства общения друг с другом, обеспечивающие информацию, которую можно, при необходимости, воспроизводить, распространять и на которую можно ссылаться. Большинство методологий разработки ПС устанавливают официальные документы для связи между задачами и специалистами. Для обеспечения качества ПС требуется документация процессов разработки и документация продукции. Сопровождающим специалистам и программистам требуется детальное описание ПС, такое, чтобы они могли локализовать и корректировать дефекты, модернизировать и изменять программы.

Стратегии документирования, подготовленные и отслеживае-

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

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

Внутри предприятия должны быть приняты стандарты и руководства для:

52

−модели жизненного цикла ПС;

−типов и взаимосвязей документов;

−содержания и структуры документов;

−качества документов;

−форматов и обозначения документов.

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

Документация разработки (технологическая) описывает про-

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

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

53

включать материалы: для пользователей, которые вводят данные, восстанавливают информацию и решают задачи с помощью ПП; для операторов, которые применяют ПП на вычислительной системе; для сопровождающих программистов, а также материалы для руководителей, которые следят за использованием комплекса программ. Типовые документы продукции включают: учебные руководства; справочные руководства и руководства пользователей; руководства по сопровождению ПП; брошюры и информационные листовки, посвященные рекламе продукции.

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

Стандартизированные форматы документов важны для кон-

троля качества документов, для читаемости документов и для облегчения их сопровождения. Форматы документов могут различаться от проекта к проекту. Они зависят от таких факторов, как объем проекта, аудитория, для которой предназначены документы, количество установленных стадий и бюджет документирования.

Основными ресурсами в стандарте, для документирования вы-

деляются: персонал; инструментальные средства; финансирование. Для процесса разработки необходимы люди со знанием: программирования; сути предмета применения ПК; документирования продукции. Важно, чтобы штат был полностью обучен методам документирования, и чтобы каждая группа специалистов полностью понимала и выполняла свою роль в процессе документирования. Проектировщики ПС и программисты создают документацию разработки; специалисты в предметной области обеспечивают информацию для стадий изучения спецификаций требований, планов тестирования и обеспечения качества, планов сборки программ. Специалисты по изданию обычно подготовляют документацию по обучению пользователей, а также справочную и информационную о продукции.

54

План документирования определяет, что должно быть сделано,

как, когда и кто это должен делать. Для больших проектов это может быть объемный документ, который следует установленным стандартам и является предметом для официальной проверки и процедуры утверждения. План документирования должен быть доведен до всех участников разрабатывающего коллектива, кого он касается. Должны быть четко установлены обязанности всех вовлеченных в работу, связанную с документированием. График документирования должен распределять время для: планирования разработки документов; проверки плана и принципов документирования; подготовки проектов и проверки их на техническую точность, полноту и соответствие; проведение согласования; распространения. Планирование следует начинать заранее, реализацию плана необходимо проверять на всем протяжении проекта.

Стандарт ISO 12182 – описывает схему классификации про-

граммных средств, охватывающую существенные характеристики и атрибуты, отражающие и определяющие ПК, их виды и классы. Установленная в стандарте классификация предназначена для определения классов конкретных ПС, и связей программных задач, процессов или продуктов и их документов со стандартами программной инженерии. В настоящем стандарте установлена схема классификации, помогающая:

− уточнить области применения используемого стандарта или

ПК;

−определить, выбрать стандарты и структуры документов, применимые к конкретному проекту ПС;

−определить классификационные характеристики новых стандартов.

Описанная в настоящем стандарте классификация может служить

вкачестве концептуальной схемы построения системы документации. Разработчики и заказчики должны применять собственные подходы к использованию данной классификации. Ее описание не основано на четко установленных потребностях разработчиков и пользователей, поэтому применение данной схемы в практической деятельности не является обязательным. Схема классификации состоит из 16 видов, которые объединены в следующие группы.

Внутренние виды:

−режим эксплуатации;

−масштаб ПС;

55

−стабильность ПС;

−функциональные возможности;

−требование защиты;

−требование надежности;

−требуемые рабочие характеристики;

−исходный язык.

Виды внешней среды:

−прикладная область информационной системы;

−вычислительная система и среда;

−класс пользователя;

−требование к вычислительным ресурсам;

−критичность ПС;

−готовность программного продукта.

Виды данных:

−представление данных;

−использование программных данных.

В зависимости от специфики ПС может быть необходимым использование дополнительных видов. В ряде случаев применения схемы классификации для представления наиболее специфичных характеристик и документации ПС может быть использована комбинация нескольких видов с конкретными классами. Схема классификации, связанная с описанием каждого вида, представляет собой перечень классов, соответствующих данному виду. В большинстве случаев такие перечни являются типовыми или открытыми, а не исчерпывающими или полными. Пользователи схемы классификации должны руководствоваться собственными соображениями при выборе и идентификации соответствующих классов для конкретного ПС или прикладной области. Примерами классов функции ПК являются:

−обработка деловых сообщений;

−компиляция;

−научные вычисления;

−обработка текстов;

−медицинские системы;

−системы управления объектами и системами;

−системы управления процессами в системах.

Для вида прикладная область системы, классы должны быть определены в зависимости от типа или класса внешней среды и системы, в которой они устанавливаются. Примерами классов прикладной области являются:

56

−наука;

−бытовые устройства;

−оборудование;

−аппаратура управления объектом или процессом;

−предпринимательство;

−система организации сети.

Для вида режим эксплуатации классы должны быть определены в зависимости от конкретных технологий или типов обработки, принятых в системе:

−пакетная обработка данных;

−обработка данных в режиме реального времени;

−обработка данных в режиме разделения времени;

−параллельная обработка данных;

−совмещенная обработка данных.

Для вида масштаб ПС должны быть определены классы в зависимости от размера или сложности ПС. Размер может быть определен в числа строк исходной программы (SLOC), исключая комментарии, и уточнен на уровне языка (в Ассемблере, Аде, Си, Java). Сложность может быть определена как функция соответствующего параметра, классов масштаба ПС на языке программирования – ориенти-

ры:

−малый (10 4 строк);

−средний (10 5 строк);

−большой (10 6 строк).

Применение стандарта в его описании иллюстрируется таблицей взаимосвязи шести характеристик качества ПС по стандарту ISO 9126 и 16-ти видов классификации комплексов программ в области действия стандарта ISO 12182.

В стандарте ISO 12207: 2008 документированию посвящен специальный раздел в группе вспомогательных процессов. Кроме того, почти все процессы и работы основного, раздела стандарта, представляющего этапы и работы жизненного цикла ПК, отражают

конкретные требования к документированию соответствующих работ.

Проектирование и разработка – каждый идентифицированный документ должен быть спроектирован (разработан) согласно соответствующим документационным стандартам для формата, описания содержания, нумерации страниц, размещения рисунков/таблиц, маркировки (отметки) права собственности/защиты и других компонентов

57

представления. Должны быть подтверждены источники и соответствие входных данных для документов. Подготовленные документы должны быть рассмотрены и отредактированы на предмет формата, технического содержания и стиля представления в соответствии с их стандартами. Они должны быть рассмотрены на соответствие и одобрены доверенным персоналом до выпуска.

Производство – документы должны быть произведены и поставлены заказчику согласно плану. Производство и дистрибуция документов может использовать электронные или другие средства. Оригинальный материал (оригинал) должен быть сохранен согласно требованиям для хранения данных, защиты, содержания и дублирования. Средства управления должны быть поставлены согласно процессу управления конфигурацией

Стандарт ГОСТ Р 51904 регламентирует документы, которые создаются в течение всего жизненного цикла ПК. Эти документы позволяют реализовать процессы и модификацию программного средства. Заказчик должен осуществлять выбор необходимого и экономически обоснованного состава и содержания документов для конкретной разработки. Заказчик разрешает любые конфликты между требованиями разрабатывающего предприятия и требованиями контракта. В настоящем стандарте не ставилась задача описать все документы, которые могут быть необходимы для разработки конкретного программного средства, и предложить конкретные методы организации информации. В отдельном разделе обсуждаются характеристики, форма, методы контроля конфигурации и содержание документов жизненного цикла ПС, при этом выделены:

−однозначность: информация является однозначной, если она написана в терминах, которые допускают только единственную интерпретацию, уточненную, если необходимо, соответствующими определениями;

−полнота: информация является полной, если она включает в себя необходимые требования и/или описательные материалы, определяет ответную реакцию для всего диапазона допустимых входных данных, используемые рисунки и таблицы сопровождаются необходимыми обозначениями, термины и единицы измерения определены;

−верифицируемость: информация является верифицируемой, если она может быть проверена на корректность человеком или инструментальным средством;

58

−согласованность: информация является согласованной, если не существует противоречий внутри нее и с внешней средой;

−модифицируемость: информация является модифицируемой, если она структурирована и имеет такой стиль, что изменения могут быть выполнены в необходимом объеме, согласованно и корректно без нарушения структуры компонента или проекта ПС;

−трасируемость: информация является трассируемой, если для каждого его компонента может быть определен корректный первоисточник.

Форма документов должна обеспечивать эффективный поиск и просмотр документов ПС в процессе обслуживания систем. Состав документов и их конкретная форма должны быть определены в Плане. Документы жизненного цикла ПС могут быть отнесены к одной из двух категорий степени контроля, в соответствии с применяемыми в стандарте методами управления конфигурацией. Введение различных категорий контроля позволяет снизить стоимость разработки в случаях, когда менее строгий контроль может быть применен без снижения допустимого качества и безопасности.

Кроме стандартов, приведенных в данном разделе, процессы документирования и рекомендуемая структура документов отражены, в той или иной степени, во многих стандартах, основная часть которых перечислена в Приложении 1.

2.2.Стандарты, регламентирующие эксплуатационную доку-

ментацию программных средств

Эксплуатационная документация должна обеспечивать эффективное применение программных продуктов в соответствии с их назначением и функциями, квалифицированными специалистамипользователями. Состав и содержание комплекта документов конкретного программного продукта, следует адаптировать разработчиками к его особенностям и свойствам на основе использования стандартов и типовых структур, представленных в п. 3.7. Разра-

ботчикидокументов должны обеспечивать комфортное и корректное применение ПС пользователями, на основе ясного и непротиворечивого изложения в документах технологических процедур и операций для функционирования и получения требуемых результатов. На базе представленного в стандарте набора и содержания документов следует выделять из них необходимые для двух классов ПС, которые в

59

наибольшей степени различаются особенностями эксплуатации. Первый класс характеризуется комплексами программ автоматизированного управления динамическими объектами и процессами в реальном масштабе времени. В процессе их применения допускается минимальное вмешательство и процедуры пользователей, и необходим, соответственно, небольшой объем эксплуатационных документов, выделяемых из базового комплекта. Для ПК второго класса возможно применение пользователями широкого набора процедур управления, которые должны быть регламентированы достаточно полным набором и подробным содержанием документов. Все последующее изложение ориентировано на этот класс ПС и в п. 3.7 представлен широкий набор базовых документов. Пользователи таких ПС можно разделить на две крупных группы, каждая из которых должна быть обеспечена комплектной эксплуатационной документацией:

−администраторы, подготавливающие ПС к эксплуатации и обеспечивающие их функционирование и использование по прямому назначению;

−операторы – пользователи, реализующие функционирование и применение программных комплексов в системе, обработку и анализ результатов.

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

−консультация разработчиков программ и данных по особенностям применения операционной системы и системы управления базой данных (СУБД);

−планирование использования памяти и производительности вычислительной системы в рабочем режиме применения ПС;

−инсталляция и генерация инструментальных средств и рабочей версии ПК для оперативного пользователя;

60