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

Стандарты

ГОСТ 19.504—79

1. Общие положения

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

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

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

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

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

2. Содержание разделов

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

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

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

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

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

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

Практика

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

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

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

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

Целевая аудитория

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

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

Содержание документа

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

Как устроен «мир», в который погружают разработчика. С какими объектами программист имеет дело, где они находятся, сколько времени существуют и как они взаимодействуют между собой. Какие из них он создает сам, а какие предоставлены ему изначально средой, фреймворком, библиотекой.
Какие еще средства разработки (кроме нашего программного продукта) необходимы для того, чтобы создать приложение или систему. Например, если наш программный продукт — это библиотека, то программисту потребуются компилятор (возможно, вполне определенный), какая-то среда разработки и прочий инструментарий.
В какой среде функционирует приложение или система? Какими будут его минимальные требования к системе? Понадобятся ли для его запуска какие-либо дополнительные программные средства: фреймворки, рантаймы, интерпретаторы.
Что представляет собой минимальное работоспособное приложение или минимальная работоспособная система. Какие объекты в какой последовательности необходимо создать, и как их друг с другом соединить, чтобы приложение вывело хотя бы «Hello World». Правда, бывают приложения, которые вообще не выводят текста, а управляют доменной печью или трафиком в сетях, но у них все равно обязательно есть какой-то свой минимальный вывод.
Как (по шагам) скомпилировать работоспособное приложение или развернуть работоспособную систему.

Это основные вопросы, без ответов на которые программист не сможет нормально работать. Если не сообщить их ему в явном виде, он будет вынужден заняться исследованиями. Но есть еще много дополнительных: методика и техника отладки, стиль программирования и др.

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

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

Методика и стиль изложения

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

При вводе нового понятия мы опираемся только на те понятия, которые были введены ранее явно или считаются заведомо знакомыми читателю. Как в учебнике математики.
У читателя никогда не должно возникать ощущение, что автор плодит сущности без надобности. Ввод каждого понятия должен быть чем-то обоснован.

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

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

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

Желательно по каждому объекту привести примеры использования, небольшие фрагменты кода, демонстрирующие:

создание объекта (если перед использованием его необходимо создать);
передачу объекту входных данных;
получение выходных данных и их интерпретацию.

Описания объектов можно вынести в отдельный том или документ под названием «Справочник программиста». Хорошая мысль — сделать его гипертекстовым.

Между теоретической частью и справочником по объектам полезно поместить небольшой раздел, в котором рассматривается пример небольшого, но полноценного, с точки зрения используемой платформы, приложения. Пример должен быть таким, чтобы читатель смог самостоятельно это приложение воспроизвести, отладить и запустить. Очевидно, для этого сначала все это должен проделать кто-то из авторов руководства программиста.

Примеры

АПК «Нострадамус». Руководство программиста

Аналитический программный комплекс «Нострадамус» предназначен для создания аналитических и отчетных банковских систем. Он содержит набор специализированных компонентов, из которых разработчик конструирует приложение в визуальной среде. Программный код в случае необходимости можно писать на языке Pascal (поэтому описание языка программирования не требуется). Программный комплекс разработан компанией «ПрограмБанк», а техническая документация «Философтом» по ее заказу. Кроме руководства программиста в комплект документации входит исчерпывающий справочник по всем компонентам АПК.

1. Общие сведения
1.1. Сокращения
1.2. Назначение
1.3. Функциональные возможности
1.4. Условия применения
1.5. Требования к квалификации разработчика
2. Прикладное решение и его компоненты
2.1. Архитектура АПК «Нострадамус». Понятие прикладного решения
2.2. Требования к прикладному решению
2.2.1. Базовые требования
2.2.2. Требования к входным данным
2.2.3. Требования к алгоритмам раcчета данных
2.2.4. Требования к отчетам и набору каждого из них
2.2.5. Требования к разграничению доступа и информационной безопасности
2.3. Компоненты прикладного решения
2.3.1. Структура базы данных
2.3.2. Загрузка исходных данных
2.3.3. Организация пользовательского интерфейса
2.3.4. Работа пользователя с данными
2.3.5. Обработка и расчет данных
2.3.6. Отображение данных
2.3.7. Средства автоматической загрузки и обработки данных. Системный агент
2.4. Разграничение прав доступа в прикладном решении
2.4.1. Роли пользователей
2.4.2. Профили пользователей
2.5. Жизненный цикл прикладного решения
3. Пример прикладного решения
3.1. Постановка задачи. Определение требований к прикладному решению
3.2. Проектирование прикладного решения
3.2.1. Проектирование структуры таблиц и процедур загрузки данных
3.2.2. Проектирование интерфейса пользователя
3.2.3. Проектирование процедур расчета и отчетов
3.3. Реализация прикладного решения
3.3.1. Авторизация в АПК «Нострадамус»
3.3.2. Создание категории решений
3.3.3. Создание таблиц
3.3.4. Создание процедур загрузки данных
3.3.5. Создание справочников и визуальных форм для них
3.3.6. Создание процедур расчета на языке хранимых процедур базы данных
3.3.7. Создание отчетов
3.3.8. Создание групп пользователей и создание главного меню для них
3.3.9. Создание процедуры автоматического обновления (загрузки) данных с помощью системного агента
3.4. Развертывание прикладного решения
3.5. Тестирование прикладного решения
3.6. Усложнение задачи
3.7. Доработка прикладного решения
3.7.1. Создание интерактивного отчета
3.7.2. Создание интерактивной загрузки
3.7.3. Финальный этап внесения доработок в прикладное решение

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

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

Введение
i. Система e-port дилер: клиент-серверный протокол. Назначение и обзор возможностей
ii. Задачи протокола
iii. Основные преимущества использования протокола
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.1. Запрос операции
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.10. Статус операции
3.10.1. Примеры сообщений о статусе операций
3.10.2. Коды состояния находящихся в обработке или завершенных операций
3.11. Уведомления системы
4. Глоссарий
Приложения
Приложение 1. DTD XML-запроса и комментарий
DTD XML-запроса
Комментарий
Приложение 2. DTD XML-ответа
Приложение 3. Правила расчета суммовых полей
Приложение 4. Примеры запросов и ответов сервера

Шаблоны

Шаблон	Описание
Филогост	Комплект шаблонов и пустографок для Microsoft Word

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