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

Когда требуется руководство программиста?

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

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

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

К типичным задачам такого документа относится:

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

Г О С У Д А Р С Т В Е Н Н Ы Й С Т А Н Д А Р Т С О Ю З А С С Р

Единая система программной документации	ГОСТ 19.504-79 (СТ СЭВ 2095-80)
РУКОВОДСТВО ПРОГРАММИСТА. ТРЕБОВАНИЯ К СОДЕРЖАНИЮ И ОФОРМЛЕНИЮ
United system for program documentation. Programmer"s guide. Requirements to contents and form of presentation

Постановлением Государственного комитета стандартов Совета Министров СССР от 12 января 1979 г. ¹ 74 срок введения установлен

с 01.01. 1980 г.

Настоящий стандарт устанавливает требования к содержанию и оформлению программного документа «Руководство программиста», определённого ГОСТ 19.101-77 .

Стандарт полностью соответствует СТ СЭВ 2095-80.

1. ОБЩИЕ ПОЛОЖЕНИЯ

1.1. Структуру и оформление документа устанавливают в соответствии с ГОСТ 19.105-78 .

Составление информационной части (аннотации и содержания) является обязательным.

1.2. Руководство программиста должно содержать следующие разделы:

• назначение и условия применения программ;
• характеристика программы;
• обращение к программе;
• входные и выходные данные;
• сообщения.

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

2.1. В разделе «Назначение и условия применения программ» должны быть указаны назначение и функции, выполняемые программой, условия, необходимые для выполнения программы (объем оперативной памяти, требования к составу и параметрам периферийных устройств, требования к программного обеспечению и т.п.).

2.2. В разделе «Характеристика программы» должно быть приведено описание основных характеристик и особенностей программы (временные характеристики, режим работы, средства контроля правильности выполнения и самовосстанавливаемости программы и т.п.).

2.3. В разделе «Обращение к программе» должно быть приведено описание процедур вызова программы (способы передачи управления и параметров данных и др.).

2.4. В разделе «Входные и выходные данные» должно быть приведено описание организации используемой входной и выходной информации и, при необходимости, ее кодирования.

2.5. В разделе «Сообщения» должны быть указаны тексты сообщений, выдаваемых программисту или оператору в ходе выполнения программы, описание их содержания и действий, которые необходимо предпринять по этим сообщениям.

2.6. В приложении к руководству программиста могут быть приведены дополнительные материалы (примеры, иллюстрации, таблицы, графики и т.п.).

* Переиздание (Ноябрь 1987 г.) с Изменением № 1, утвержденным в сентябре 1981 г (ИУС 11-81)

УФИМСКИЙ ГОСУДАРСТВЕННЫЙ АВИАЦИОННЫЙ ТЕХНИЧЕСКИЙ УНИВЕРСИТЕТ

КАФЕДРА ВЫЧИСЛИТЕЛЬНОЙ МАТЕМАТИКИ И КИБЕРНЕТИКИ

Прикладное программное обеспечение для учета заявок и контроля их исполнения на примере ООО «Интегрированная транспортная сеть».

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

1. Аннотация

Приводится руководство программиста программного обеспечения для учета заявок и контроля их исполнения на примере ООО «Интегрированная транспортная сеть».

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

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

1. Назначение программы

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

1. 2. Условия, необходимые для выполнения программы

Для работы программного продукта необходима следующая программно-аппаратная конфигурация:

Windows 7,Windows Server 2003 Service Pack 2,Windows Server 2008,Windows Server 2008 R2,Windows Vista, Windows Vista Service Pack 1,Windows XP Service Pack 2,Windows XP Service Pack 3;

32-разрядные системы: компьютер, оборудованный процессором Intel или совместимым процессором с тактовой частотой 1 ГГц или выше (рекомендуется 2 ГГц или выше, поддерживается только один процессор);

64-разрядные системы: процессор с тактовой частотой 1,4 ГГц или выше (рекомендуется 2 ГГц или выше, поддерживается только один процессор);

1 ГБ свободного места на диске;

наличие СУБД: MS SQL 2008;

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

3.1. Режим работы программы

Диалоговый. Web-интерфейс в браузере (с поддержкой HTML5).

3.2.Средства проверки правильности выполнения программы

Проверка правильности работы программы осуществляется при выполнении конкретных примеров. Программа выдает сообщение при вводе некорректных данных (Рис. 2.20):

Рис. 2.20. Некорректный ввод номера телефона

3.3. Функционирование программы после сбоев

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

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

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

Запустить программу на ПК, с поддержкой Microsoft .NET Framework (или на удаленном сервере), если он еще не запущен;

Откройте ваш любимый браузер (на пример chrome, internet explorer, mozilla firefox);

Введите в адресную строку IP-адрес сервера, с заранее определенным портом;

Откроется страница домашняя страница;

Начать работу с клиентами.

Руководство пользователя составляют на основании ГОСТ 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 Очередь

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

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

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

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

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

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

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

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

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

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

3.9 Справочник

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

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

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

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

4 ГЛОССАРИЙ

ПРИЛОЖЕНИЯ

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

Создан 02.02.2010 9:34:31

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

В разделе «Назначение и условия применения программ» должны быть указаны назначение и, условия, необходимые для выполнения программы (объем, к составу и параметрам, требования к и т.п.) [из п. 2.1 ГОСТ 19.504-79]

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

В разделе «Характеристика программы» должно быть приведено описание основных характеристик и особенностей программы (временные характеристики, режим работы, средства контроля выполнения и самовосстанавливаемости программы и т.п.) [из п. 2.2 ГОСТ 19.504-79]

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

В разделе «Обращение к программе» должно быть приведено описание процедур вызова программы (способы передачи управления и параметров данных и др.) [из п. 2.3 ГОСТ 19.504-79]

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

В разделе «Входные и выходные данные» должно быть приведено описание организации используемой входной и выходной информации и, при необходимости, ее [из п. 2.4 ГОСТ 19.504-79]

Сообщения

В разделе «Сообщения» должны быть указаны тексты сообщений, выдаваемых программисту или в ходе выполнения программы, описание их содержания и действий, которые необходимо предпринять по этим сообщениям [из п. 2.5 ГОСТ 19.504-79]

Приложения

В приложении к руководству программиста могут быть приведены дополнительные материалы (примеры, иллюстрации, таблицы, графики и т.п.) [из п. 2.6 ГОСТ 19.504-79]