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

Руководство пользователя составляют на основании ГОСТ 19.504-79. Руководство программиста разрабатывают в трех случаях:

– программный продукт по своему основному назначению является средой разработки или библиотекой (как Delphi или Qt);

– комплекс или программный продукт служит платформой для разработки программ или систем определенного типа (как 1С или Axapta);

– программа распространяется вместе с исходным кодом или постоянно модифицируется самими разработчиками.

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

Руководство программиста должно объяснять:

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

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

– В какой среде функционирует приложение или система. Какими будут его минимальные требования к системе. Понадобятся ли для его запуска какие-либо дополнительные программные средства: фреймворки, рантаймы, интерпретаторы.

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

– Как (по шагам) скомпилировать работоспособное приложение или развернуть работоспособную систему.

Кроме того руководство программиста должно содержать полные описания всех предусмотренных в программном продукте объектов. Если это функции, то должны быть приведены их синопсисы, если классы, то описания их интерфейсов и т. Д.

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

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

– При вводе нового понятия следует опираться только на те понятия, которые были введены ранее или заведомо знакомы читателю.

– Ввод каждого понятия должен быть чем-то обоснован.

Основное требование при описании отдельных объектов — полнота описания каждого из них.

При описании объектов особое внимание следует уделять следующим аспектам:

– Что обязательно должно предшествовать созданию и использованию объекта.

– Каковы побочные эффекты обращения к объекту.

– Особенности интерпретации объектом передаваемых ему данных.

– Где «физически» (в каком файле, в какой библиотеке) находится объект.

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

Возможно выполнение руководства программиста гипертекстовым.

Структура руководства программиста:

1. Назначение и условия применения программы.

2. Характеристика программы.

3. Обращение к программе.

4. Входные и выходные данные.

5. Сообщения.

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

В качестве примера представлено содержание руководства программиста Система e-port дилер. Клиент-серверный протокол.

Система «e-port дилер» предназначена для приема и проведения моментальных платежей при оплате услуг мобильной связи, доступа в Интернет и т. П. Центральный сервер системы принадлежит группе e-port, а пункт приема платежей может открыть любой желающий, установив у себя на компьютере (подключенном к Интернету) программу-клиент. Обмен данными между центральным сервером и программой-клиентом осуществляется по специальному протоколу. Протокол открытый, что позволяет различным организациям: банкам, розничным сетям, сетям платежных терминалов, осуществлять платежи непосредственно из собственных систем. Протокол разработан Группой e-port, а техническая документация «Философтом»по ее заказу.

ВВЕДЕНИЕ

Система e-port дилер: клиент-серверный протокол. Назначение и обзор возможностей

Задачи протокола

Основные преимущества использования протокола

1 Реализация протокола (шлюз)

1.1 Общие сведения

1.2 Структура приложения

2. Как работает шлюз

2.1 Регистрация и отчетность

2.1.1 Регистрация

2.1.2 Отчетность

2.2 Обмен данными с сервером

2.2.1 Структура пакета

2.2.2 Справочники

2.2.3 Порядок обмена пакетами

2.3 Цикл обработки операции

2.3.. Запрос операции

2.3.2 Очередь

2.3.3 Анализ ответа сервера

2.3.4 Нестандартные ситуации

3 Спецификация протокола

3.1 Структурные элементы пакета

3.2 Заголовок запроса

3.3 Заголовок ответа

3.4 Пополнение счета

3.5 Покупка PIN-кода

3.6 Прерывание процесса обработки операции

3.7 Транзакционные свойства операции

3.8 Запрос на проведение нескольких операций

3.9 Справочник

3.11 Статус операции

3.11.1 Примеры сообщений о статусе операций

3.11.2 Коды состояния находящихся в обработке или завершенных операций

3.11 Уведомления системы

4 ГЛОССАРИЙ

ПРИЛОЖЕНИЯ

Приложение 1. DTD XML-запроса и комментарий

DTD XML-запроса

Комментарий

Приложение А DTD XML-ответа

Приложение Б. Правила расчета суммовых полей

Приложение В Примеры запросов и ответов сервера