Руководство программиста
Wiki для разработчиков технической документации
Чтобы стать редактором Wiki оставьте заявку в произвольной форме на форуме
|
| ||
|
С чего начать написание Руководство программиста? (обсуждение на форуме) Цели и задачи Руководство программиста разрабатывают в трех случаях: программный продукт по своему основному назначению является средой разработки или библиотекой (как Delphi или Qt); комплекс или программный продукт служит платформой для разработки программ или систем определенного типа (как 1С или Axapta); программа распространяется вместе с исходным кодом или постоянно модифицируется самими разработчиками. Наверняка можно представить себе и другие ситуации (например, программный продукт является операционной системой), но в жизни они встречаются значительно реже. Очевидная задача руководства программиста — снабдить разработчика информацией, которой ему будет достаточно для создания на базе нашего программного продукта собственных программ или систем. Еще один мотив создания такого документа — потребность разработчиков время от времени фиксировать состояние продукта, чтобы самим в нем не запутаться и не плодить в коллективе носителей «сакральных знаний». Содержание документа Руководство программиста должно объяснять: Как устроен «мир», в который погружают разработчика. С какими объектами программист имеет дело, где они находятся, сколько времени существуют и как они взаимодействуют между собой. Какие из них он создает сам, а какие предоставлены ему изначально средой, фреймворком, библиотекой. Какие еще средства разработки (кроме нашего программного продукта) необходимы для того, чтобы создать приложение или систему. Например, если наш программный продукт — это библиотека, то программисту потребуются компилятор (возможно, вполне определенный), какая-то среда разработки и прочий инструментарий. В какой среде функционирует приложение или система? Какими будут его минимальные требования к системе? Понадобятся ли для его запуска какие-либо дополнительные программные средства: фреймворки, рантаймы, интерпретаторы. Что представляет собой минимальное работоспособное приложение или минимальная работоспособная система. Какие объекты в какой последовательности необходимо создать, и как их друг с другом соединить, чтобы приложение вывело хотя бы «Hello World». Правда, бывают приложения, которые вообще не выводят текста, а управляют доменной печью или трафиком в сетях, но у них все равно обязательно есть какой-то свой минимальный вывод. Как (по шагам) скомпилировать работоспособное приложение или развернуть работоспособную систему. Это основные вопросы, без ответов на которые программист не сможет нормально работать. Если не сообщить их ему в явном виде, он будет вынужден заняться исследованиями. Но есть еще много дополнительных: методика и техника отладки, стиль программирования и др. Кроме теории руководство программиста должно содержать полные описания всех предусмотренных в программном продукте объектов. Если это функции, то должны быть приведены их синопсисы, если классы, то описания их интерфейсов и т. д. Если программный продукт предполагает использование оригинального языка программирования и снабжен собственным компилятором или интерпретатором, в руководство программиста необходимо включить его описание. Однако, если оно получается достаточно объемным, его выносят в отдельный документ, который так и называется: описание языка (программирования). Методика и стиль изложения Важнейшие методические требования к теоретической части руководства программиста — логичность и последовательность изложения. В частности, в тексте обязательно должны быть соблюдены следующие правила: При вводе нового понятия мы опираемся только на те понятия, которые были введены ранее явно или считаются заведомо знакомыми читателю. Как в учебнике математики. У читателя никогда не должно возникать ощущение, что автор плодит сущности без надобности. Ввод каждого понятия должен быть чем-то обоснован. Основное требование при описании отдельных объектов — полнота описания каждого из них. В отличие от руководства пользователя, при составлении которого в принципе можно рассчитывать на догадливость читателя, который поглядит на интерфейс и сам разберется, руководство программиста описывает весьма неочевидные вещи. И хотя от программиста можно ожидать большей догадливости, чем от пользователя, восполнять недостаток информации ему придется анализом исходного текста, а если он доступен, то тестированием «черного ящика» и отладчиком. Это намного более долгий процесс, чем «блуждание» по меню и диалоговым окнам. При описании объектов особое внимание следует уделять следующим аспектам:
Между теоретической частью и справочником по объектам полезно поместить небольшой раздел, в котором рассматривается пример небольшого, но полноценного, с точки зрения используемой платформы, приложения. Пример должен быть таким, чтобы читатель смог самостоятельно это приложение воспроизвести, отладить и запустить. Очевидно, для этого сначала все это должен проделать кто-то из авторов руководства программиста. Типовая структура руководство программиста Структура руководства программиста, зафиксированная в ГОСТ 19.504-79, такова:
Полноценное руководство программиста может быть написано только автором, имеющим собственный опыт профессиональной разработки программ. Руководство программиста может комплектоваться различными схемами, например, схемами базы данных, диаграммами классов, графами вызова функций. | Зарегистрируйтесь | |