Документирование программного обеспечения

Колледж Информатики и Вычислительной Техники

Факультет программирования

РЕФЕРАТ

Дисциплина: технология программирования.

Тема: документирование программного обеспечения.

Выполнил студент:

Таллинн

2003

Содержание

1. Документирование программного обеспечения.

1.1 Техническое задание.

1.2 Внешние и внутренние языки спецификации.

1.3 Руководство пользователя.

1.4 Руководство программиста.

Документирование программного обеспечения

Когда программист-разработчик получает в той или иной форме задание на программирование, перед ним, перед руководителем проекта и перед всей проектной группой встают вопросы: что должно быть сделано, кроме собственно программы? что и как должно быть оформлено в виде документации? что передавать пользователям, а что — службе сопровождения? как управлять всем этим процессом? Кроме упомянутых вопросов есть и другие, например, что должно входить в само задание на программирование? Прошло много лет, программирование происходит в среде совершенно новых технологий, многие программисты, работая в стиле drag-and-drop, могут годами не видеть текст своих программ. Это не значит, что исчезла необходимость в их документировании. Более того, вопросы о наличии хоть какой-то системы, регламентирующей эту сторону создания программных средств, продолжают задавать постоянно. Спрашивают и о том, есть ли обязательные для применения стандарты (особенно остро стоит этот вопрос, когда разработка выполняется по заказу государственной организации или предприятия). Интересуются и тем, где можно купить имеющиеся стандарты.

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

Техническое задание

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

Техническое задание на разработку ПО должно включать следующие разделы:

введение;

основания для разработки;
назначение разработки;
требования к программе;
требования к программной документации;
технико-экономические показатели;
стадии и этапы разработки;
порядок контроля и приемки;
приложения.

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

В разделе “Введение” указывается наименование, краткая характеристика области применения ПО.

В разделе “Основания для разработки” указывается:

 

документ (документы), на основание которых ведется разработка;
организация, утвердившая документ, и дата утверждения;
наименование (условное обозначение) темы разработки.

В разделе Назначение разработки должно быть указано функциональное и эксплуатационное назначение ПО.

Например, UML – как универсальный язык моделирования. Может использоваться и для постановки технического задания.

Внешние и внутренние языки спецификации

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

 

Соглашение о требованиях;
Внешняя спецификация;
Внутренняя спецификация.

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

Ниже приведена общая структура документа “Внешняя спецификация”, с развернутыми комментариями в тех пунктах, которые касаются технической стороны дела

1. ОПИСАНИЕ ПРОГРАММНОГО ИЗДЕЛИЯ

1.1. Наименование и шифры ПО (полное наименование, сокращенные наименования, шифры ПО и проекта).

1.2. Краткое описание ПО (включая сведения об авторском праве, иерархию документов, с указанием документов вышестоящих уровней).

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

2. ЦЕЛИ

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

3. СТРАТЕГИЯ

3.1. Соглашения относительно представления материала.

3.1.1. Обозначения (определяются все обозначения, используемые в требованиях: например, если применяются индексы, то дается пример их использования и определяется принцип индексации).

3.1.2. Терминология (особенно специфическая для данного изделия).

3.1.3. Синтаксис (приводятся, если необходимо, синтаксические правила для дальнейшего описания требований).

3.2. Генерируемое программное обеспечение (классифицируется как вспомогательное и порождаемое описываемым изделием).

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

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

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

3.3.n.1. Внешние ограничения.

3.3.n.1.1. Стандарты (список используемых промышленных стандартов и собственных стандартов предприятия).

3.3.n.1.2. Ограничения на совместимость. Необходимо рассматривать несколько аспектов совместимости:

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

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

изделиями-компаньонами (т.е. относящимися к той же группе средств и являющимися альтернативой);

подобными изделиями (т.е. выполняющих похожие функции в других программных изделиях); конкурирующими изделиями (других организаций).

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

3.3.n.1.4. Аппаратные ограничения. Приводится перечень устройств, необходимых для работы ПО (с указанием минимальной, оптимальной и максимальной конфигурации). Указываются все действующие ограничения на оборудование, например, физические характеристики терминала или требование запрещения использования звукового сигнального устройства.

3.3.n.2. Внешние характеристики.

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

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

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

3.3.n.2.3. Входы. Описание подобно п. 3.3.2.1

3.3.n.3. Эргономические характеристики.

Примечание. Этот раздел описывает свойства, обеспечивающие надежность, комфорт и продуктивность работы пользователей и операторов, а также вопросы безопасности, секретности, восстанавливаемости после сбоев, мобильности ПО. Остановимся более подробно на двух подразделах: Надежность и Рабочие характеристики.

В разделе Надежность (это свойство программы понимается здесь как способность к восстановлению нормальной работы при ошибках и сбоях в работе оборудования) рассматриваются следующие вопросы:

защита данных пользователя;

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

Раздел “Рабочие характеристики” описывает основные параметры или принципы, по которым должна оцениваться эффективность работы программы, по возможности в количественном виде с указанием возможных допусков. Все параметры должны быть измеряемыми, к их числу могут относиться быстродействие, пропускная способность, скорость передачи данных, расход машинных ресурсов, время реакции (или задержки) и т.д.

3.3.n.4. Внутренние характеристики (этот раздел полностью расширяется в документе “Внутренняя Спецификация”, однако частично может быть заполнен с целью полного описания соответствующих внешних свойств).

3.4. Внутренние ограничения (здесь речь идет о тех свойствах, которые пользователю логично ожидать, но которые по тем или иным причинам будут исключены из программного изделия или потенциально оставлены на усмотрение разработчика: например, неполная взаимозаменяемость носителей, отсутствие поддержки каких-либо возможностей оборудования, и т.п.).