Заказать звонок
-->

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

Wiki для разработчиков технической документации


Чтобы стать редактором Wiki оставьте заявку в произвольной форме на форуме 



С чего начать написание Руководство программиста? (обсуждение на форуме)

Цели и задачи 

Руководство программиста разрабатывают в трех случаях: 
программный продукт по своему основному назначению является средой разработки или библиотекой (как Delphi или Qt); 
комплекс или программный продукт служит платформой для разработки программ или систем определенного типа (как 1С или Axapta); 
программа распространяется вместе с исходным кодом или постоянно модифицируется самими разработчиками. 
Наверняка можно представить себе и другие ситуации (например, программный продукт является операционной системой), но в жизни они встречаются значительно реже. 
Очевидная задача руководства программиста — снабдить разработчика информацией, которой ему будет достаточно для создания на базе нашего программного продукта собственных программ или систем. Еще один мотив создания такого документа — потребность разработчиков время от времени фиксировать состояние продукта, чтобы самим в нем не запутаться и не плодить в коллективе носителей «сакральных знаний». 

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


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


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


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


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


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


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


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


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

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

Структура руководства программиста, зафиксированная в ГОСТ 19.504-79, такова: 
  • Назначение и условия применения программы.
  • Характеристика программы.
  • Обращение к программе.
  • Входные и выходные данные.
  • Сообщения. 


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



0

Зарегистрируйтесь
Рейтинг@Mail.ru