Промышленные технологии проектирования ПОkspt.icc.spbstu.ru...

Промышленные технологии

проектирования ПО

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

Ицыксон В.М. ПТППО (С) 2010

Документирование

� Виды документации

� Проектная документация

� Программная документация

� Эксплутационная документация

� Рабочая документация (*)


Проектная документация

� Должна создаваться в начале проекта имодифицироваться по мере продвижения проекта

� Стандарты:

� ГОСТ 19.201-78 ЕСПД. Техническое задание. Требования к содержанию и оформлению.

� ГОСТ 34.602-89 Информационная технология. Комплекс стандартов на автоматизированныесистемы. Техническое задание на созданиеавтоматизированной системы

� ГОСТ 19.301-79 ЕСПД. Программа и методикаиспытаний. Требования к содержанию иоформлению.


Программная документация

� Должна создаваться в одновременно с реализациейпроекта и модифицироваться процессе эволюциипроекта

� Стандарты:� ГОСТ 19.202-78 ЕСПД. Спецификация. Требования к

содержанию и оформлению.� ГОСТ 19.401-78 ЕСПД. Текст программы Требования к

содержанию и оформлению� ГОСТ 19.402-78 ЕСПД. Описание программы.� ГОСТ 19.504-79 ЕСПД. Руководство программиста.

Требования к содержанию и оформлению� ГОСТ 19.701-90 (ИСО 5807-85) ЕСПД. Схемы алгоритмов,

программ, данных и систем. Обозначения условные иправила выполнения. (Вместо ГОСТ 19.002-80, ГОСТ19.003-80)


Эксплутационнаядокументация

� Должна создаваться по окончании проекта

� Стандарты:

� ГОСТ 19.505-79 ЕСПД. Руководство оператора. Требования к содержанию и оформлению.

� ГОСТ 19.508-79 ЕСПД. Руководство потехническому обслуживанию. Требования ксодержанию и оформлению.

� ГОСТ 19.503-79 ЕСПД. Руководствосистемного программиста. Требования ксодержанию и оформлению


Рабочая документация

� Документация, отражающая текущее состояниепроекта

� Рабочая документация подчиняется толькокорпоративным стандартам документирования

� Рабочая документация должна изменяться вместе спроектом

� Рабочая документация должна версионироватьсявместе с проектом

� На стадии выпуска рабочая документация можетстать программной документацией илиэксплутационной документацией

� Обычной практикой является электронное ведениерабочей документации


Рабочая документация

� Вариант ведения электроннойдокументации - портал проекта� Разделяемое дисковое пространство

� Группы новостей

� Списки рассылки

� Wiki

� Коммерческие системы организациисовместной работы

� MS Sharepoint

� IBM Lotus

� И т.п.


Изобразительные средствадокументации

� Текстовая документация

� Графическая документация

� Схемы программ

� Схемы алгоритмов

� Схемы данных

� UML-диаграммы

� И т.п.

� Динамическая документация (*)

КА протокола TCP

LISTEN

CLOSED

SYN SENT

ESTABLISHED

SYN RCVD

LAST LACK

CLOSE-WAIT

FIN-WAIT1

TIME-WAIT

CLOSINGFIN-WAIT2

Вызов

close

Посылка

FIN

Получение

ACK для FIN

Получение FINПосылка ACK


Получение

ACK для FIN

Получение

ACK для FIN


Вызов closeПосылка FIN

TimeoutT=2*MSL

Посылка SYN

Вызов

close

Вызов

listen

Получение

ACK

Получение SYNПосылка ACK

Получение SYN,ACKПосылка ACK

Вызов closeПосылка FIN

Получение SYNПосылка ACK


Использование UML вдокументировании

� UML является:� Средством описания архитектуры и

особенностей реализацииинформационных систем

� Средством общения заказчика ипроектировщика

� Формальной моделью (артефактом) какой-либо стадии проектирования

� Способом документированияинформационной системы


Использование UML вдокументировании

� Используются на всех стадиях проектирования:� Сбор и разработка требований� Диаграмма случаев использования

� Диаграммы деятельностей

� Разработка архитектуры� Диаграммы классов

� Диаграммы последовательностей� Диаграммы взаимодействия

� Диаграммы деятельностей

� Диаграммы пакетов

� Реализация� Диаграммы классов

� Диаграммы объектов

� Диаграммы состояний� Диаграммы последовательностей

� Диаграммы взаимодействия

� Диаграммы пакетов

� Тестирование� Диаграмма случаев использования

� Сопровождение� Диаграмма компонентов

� Диаграмма развертывания


Генерация документации

� Впервые предложил Д. Кнут – язык WEB� Концепция «грамотного» программирования� Объединения текста и документации� Один компилятор для получения объектного кода� Второй компилятор для получения документации

� Сейчас основной подход – аннотирование текстапрограммы с помощью структурированныхкомментариев� Описание модулей� Описание функций, классов� Описание переменных� Описание параметров функций и методов� И т.п.



� На основании аннотаций и текстапрограммы генерируется системадокументов:� html – страницы

� Документ Word, rtf

� Документ PDF

� Документы XML

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

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



� Генераторы документации� Javadoc

� http://java.sun.com/j2se/javadoc/

� Cppdoc

� http://www.cppdoc.com/

� Pasdoc

� http://sourceforge.net/projects/pasdoc/

� Cdoc

� http://www.annexia.org/freeware/cdoc

� Многоязыковые:

� Doxygen http://www.doxygen.org/


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

аннотации в стиле JavaDoc

/**

* Проверяет, допустимый ли ход.

* Например, чтобы задать ход e2-e4, напишите isValidMove(5,2,5,4);

* @author John Doe

* @param theFromFile Вертикаль, на которой находится фигура (1=a, 8=h)

* @param theFromRank Горизонталь, на которой находится фигура (1...8)

* @param theToFile Вертикаль клетки, на которую выполняется ход (1=a, 8=h)

* @param theToRank Горизонталь клетки, на которую выполняется ход (1...8)

* @return true, если ход допустим, и false, если недопустим

*/

boolean isValidMove(int theFromFile, int theFromRank, int theToFile,

int theToRank)

{

. . .

}


Промышленные технологиидокументирования

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

� Отделение семантики от форматирования

� Генерация многих видов документов изодной основы:� Генерация программной документации (HTML,

PDF, ODF, Word)

� Генерация эксплутационной документации(HTML, PDF, ODF, Word)

� Интерактивные системы помощи (help)

� И т.п.


Промышленные технологиидокументирования

� Коммерческие системы

� AuthorIT

� Adobe Framemaker

� Свободно-распространяемыесистемы

� LaTeX

� DocBook

� DITA


Система LaTeX

� Набор макрорасширений для TeX

� Используется система тэгов дляформатирования документов

� Поддерживается экспорт во всепопулярные форматы


Пример форматированияLaTeX\documentclass[12pt]{article} % Вот это комментарий, он не будет показан в выходном

файле. \usepackage[russian]{babel} % Включаем пакет для поддержки русского языка. \title{\LaTeX} \date{} \author{} \begin{document} \maketitle\LaTeX{} "--- это своего рода препроцессор текста для

\TeX{} "--- программы компьютерной вёрстки. \LaTeX{} является программируемым и расширяемым, что позволяетавтоматизировать большую часть аспектов набора, включая нумерацию, перекрёстные ссылки, таблицы иизображения (их размещение и подписи к ним), общийвид страницы, библиографию и многое-многое другое. \LaTeX{} был первоначально написан Лэсли Лампортом в1984-м году и стал наиболее популярным способомиспользования \TeX{}а; очень мало людей сегодня пишутна оригинальном \TeX{}е. Текущей версией является\LaTeXe.

\newline\begin{eqnarray}

E &=& mc^2\\m &=& \frac{m_0}{\sqrt{1-\frac{v^2}{c^2}}}

\end{eqnarray} \end{document}


DITA

� Darwin Information TypingArchitecture

� Представлена IBM

� OASIS: DITA 1.0, 2005 г.

� http://www.oasis-open.org/committees/dita

� XML–документы и DTD-темы

� Охватывает весь цикл разработки, выпуска технической документации


DocBook

� Текущая версия DocBook 5.0

� Стандарт OASIS: DocBook 4.4, 2005 г.

� www.docbook.org

� Набор XML-тэгов, структурирующих элементыдокументации

� Регламентируется XML-схемой

� DocBook предоставляет более 400 тэгов

� Независимость содержания от представления

� Принцип единого источника

� Легко конвертируется в любой формат

� Существуют DocBook-редакторы и фильтры дляпопулярных текстовых процессоров


Пример документа DocBook<variablelist><title>Входы пакета pk_name</title>

<varlistentry><term>name_short(a_name)</term><listitem><para>Принимает необработанное название и возвращает его

<systemitem>краткую форму нормализованного названия</systemitem>. </para></listitem>

</varlistentry><varlistentry>

<term>name_trans(a_name)</term><listitem><para>Принимает <systemitem>полную форму нормализованного

названия</systemitem> и возвращает <systemitem>краткую форму

нормализованного названия</systemitem>. </para></listitem>

</varlistentry><varlistentry>

<term>name_full(a_name)</term><listitem><para>Принимает необработанное название и возвращает его

<systemitem>полную форму нормализованного названия</systemitem>. </para></listitem>

</varlistentry></variablelist>

Промышленные технологии проектирования ПОkspt.icc.spbstu.ru...

Documents

Transcript of Промышленные технологии проектирования ПОkspt.icc.spbstu.ru...