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

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

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

Документация: программная/эксплуатационная
Предмет: программа, комплекс, программный компонент комплекса или системы
Аудитория: программисты, сопровождающие программу или использующие ее в качестве платформы либо средства разработки при создании собственных программ
Задачи: обеспечить программисту возможность решать задачи, которые могут быть перед ним поставлены в отношении этой программы
Стандарты: ГОСТ 19.504-79

Цели и задачи

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

  1. программный продукт по своему основному назначению является средой разработки или библиотекой (как Delphi или Qt);
  2. комплекс или программный продукт служит платформой для разработки программ или систем определенного типа (как 1С или Axapta);
  3. программа распространяется вместе с исходным кодом или постоянно модифицируется самими разработчиками.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Типовая структура

Структура руководства программиста, зафиксированная в ГОСТ 19.504-79, такова:

  1. Назначение и условия применения программы.
  2. Характеристика программы.
  3. Обращение к программе.
  4. Входные и выходные данные.
  5. Сообщения.

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

  1. Руководство программиста по среде разработки «Нострадамус» (ПрограмБанк).
  2. Система e-port дилер. Клиент-серверный протокол (Группа e-port).

Особенности

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

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

Примеры

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

Аналитический программный комплекс «Нострадамус» предназначен для создания аналитических и отчетных банковских систем. Он содержит набор специализированных компонентов, из которых разработчик конструирует приложение в визуальной среде. Программный код в случае необходимости можно писать на языке 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. Примеры запросов и ответов сервера

© «Философт», 2008–2017

+7 (499) 500-44-77

mail@philosoft.ru

SpyLOG