Документирование программных средств

Должна быть определена схема  нумерации страниц.

1. Каждая страница должна  иметь индивидуальный номер. Номера  страниц должны быть проставлены  в порядке их брошюрования.

2. При брошюровке документа  с заменяемыми страницами схема  нумерации должна учитывать номер  текущей главы (раздела) с номером  страницы в данной главе (разделе), например «1-1», «1-2» и т.д. (тем  самым обеспечивается вставка  страниц в документ без перенумерации всех последующих страниц).

3. В случае брошюровки  документа без замены страниц  используют порядковую нумерацию,  например «1», «2» и т.д. Иногда  для нумерации страниц содержания  используют другую схему («i»,  «ii» и т.д.). Следует избегать схожих методов нумерации страниц вспомогательного (указателя и т.д.) и вводного материалов, так как это может привести к неоднозначности в случае изъятия или вставки страниц.

• Нумерация таблиц и рисунков.

Должны быть определены схемы  нумерации рисунков и таблиц (при  необходимости их нумерации).

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

 

 

 

ГЛАВА 2. Проектная документация

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

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

Часто при составлении  технической документации используются автоматизированные средства — генераторы документации, такие как Doxygen, javadoc, NDoc и другие. Они получают информацию из специальным образом оформленных комментариев в исходном коде, и создают справочные руководства в каком-либо формате, например, в виде текста или HTML.

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

Документация по сопровождению  программного средства (system documentation) описывает программное средство с точки зрения ее разработки.

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

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

1. документация, определяющая  строение программ и структур  данных ПС и технологию их  разработки;

2. документацию, помогающую  вносить изменения в программное  средство.

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

Внешнее описание программного средства (Requirements document).

Описание архитектуры  программного средства (description of the system architecture), включая внешнюю спецификацию каждой ее программы.

Для каждой программы программного средства - описание ее модульной структуры, включая внешнюю спецификацию каждого  включенного в нее модуля.

Для каждого модуля - его  спецификация и описание его строения (design description).

Тексты модулей на выбранном  языке программирования (program source code listings).

Документы установления достоверности  программного средства (validation documents), описывающие, как устанавливалась достоверность каждой программы программного средства и как информация об установлении достоверности связывалась с требованиями к программному средству.

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

Документация второй группы содержит

Руководство по сопровождению  программного средства (system maintenance guide), которое описывает известные проблемы вместе с программным средством, описывает, какие части системы являются аппаратно- и программно- зависимыми, и как развитие программного средства принято в расчет в его строении (конструкции).

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

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

 

 

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

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

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

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

введение;

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

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

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

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

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

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

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

Техническое задание позволяет:

- исполнителю — понять  суть задачи, показать заказчику  «технический облик» будущего  изделия, программного изделия  или автоматизированной системы; 

- заказчику — осознать, что именно ему нужно; 

- обеим сторонам —  представить готовый продукт; 

- исполнителю — спланировать  выполнение проекта и работать  по намеченному плану; 

- заказчику — требовать  от исполнителя соответствия  продукта всем условиям, оговорённым  в ТЗ;

- исполнителю — отказаться  от выполнения работ, не указанных  в ТЗ;

- заказчику и исполнителю  — выполнить попунктную проверку готового продукта (приёмочное тестирование — проведение испытаний);

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

В зависимости от ожиданий заказчика существует три альтернативы для выбора шаблона Технического задания. Если заказчик требует оформления документации в соответствии с государственным  стандартом, выбор делается в сторону  стандарта ГОСТ 34.602-89. Подготовка Технического задания по ГОСТ 34.602-89 требует значительных временных затрат.

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

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

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

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

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

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