Интернет, компьютеры, софт и прочий Hi-Tech

Подписаться через RSS2Email.ru

Документация для программиста — виды и особенности

Документация для программиста — виды и особенности

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

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

Техническое задание (ТЗ)

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

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

Техническое задание обычно содержит:

  1. Введение (наименование программы, её назначение, область применения).
  2. Требования (к функциональным характеристикам, к надёжности, к защите от некорректных действий оператора).
  3. Условия эксплуатации (требования к квалификации персонала, к техническим средствам, программной совместимости с другим софтом, к наличию исходных кодов).
  4. Техническая документация (требования к её составу, руководство для оператора, методика тестирования).
  5. Технико-экономические показатели (сугубо индивидуальные для конкретного софта).
  6. Этапы разработки (работа с документацией, создание программы, её тестирование и внедрение).
  7. Порядок контроля и приёмки (приёмка строго по оговорённому протоколу, подписание акта об осуществлении таковой).

UML-диаграммы

Аббревиатура расшифровывается как «Unified Modeling Language», что в переводе с буржуйского означает «унифицированный язык моделирования». А если конкретнее, то сие есть графический язык для объектного моделирования при разработке программного обеспечения.

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

Структура языка UML довольно сложная, но всё же не настолько, чтобы для её осмысления требовались героические умственные усилия:

Сущности:

  1. Структурные: a) классы; b) интерфейсы; c) кооперации; d) прецеденты; e) активные классы; f) компоненты; g) узлы.
  2. Поведенческие (взаимодействия, автоматы).
  3. Группирующие (пакеты).
  4. Аннотационные (примечания).

Отношения:

  1. Зависимости
  2. Ассоциации
  3. Обобщения
  4. Реализации

Диаграммы:

  1. Классов
  2. Объектов
  3. Прецедентов
  4. Кооперации
  5. Состояний
  6. Действий
  7. Последовательностей
  8. Компонентов
  9. Развёртывания

Техническая документация

Описания API

Хотите, чтобы программы взаимодействовали друг с другом? Или желаете прикрутить к своему сайту готовый веб-сервис с какого-нибудь портала? Или написать для него, сервиса, приложение? Тогда вам необходимо описание API, в коем подробно растолковано, что какая функция делает, где какой класс, процедура, константа и так далее.

В общем, вам предоставляется готовый программный интерфейс (всего лишь интерфейс, а не сам софт). Можете использовать для создания приложений.

То же самое относится и к целым операционным системам. А ради совместимости приложений с разными ОС приходится создавать «промежуточные» API и преобразователи системных вызовов (например, Wine).

API имеются у графических интерфейсов (Qt, GTK), звуковых интерфейсов (DirectSound), да и вообще у чего угодно.

Есть также Web API, роль которого очевидна из названия. Можете посмотреть, как это выглядит, открыв описание API, например, сайта «Вконтакте».

Схемы БД и прочих систем

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

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

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

Обучающая документация

Обучающая документация делится на две основные категории, которые условно можно назвать «научно-популярная» и «инструктивная».

К «научно-популярной» относятся статьи (в том числе и эта), заметки, обзоры etc., в которых человеческим языком рассказывается, для каких целей нужны те или иные решения, в чём их суть и нужно ли в них углубляться, не проигнорировать ли новомодное явление.

«Инструктивная» — справочные материалы для тех, кому углубляться всё же нужно. Мол, чтобы было вот так, надо вот здесь сделать это и это, тогда будет вам счастье.

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

Вообще слово «manual» уже давно обозначает не только «ручной», но и «руководство по эксплуатации». (Вместо старого доброго понятия «handbook».) Отсюда произошла и команда man в GNU/Linux, выводящая в терминале простейшую разновидность справочной документации для других команд. Так что если побороть лень и читать побольше, то можно действительно чему-нибудь научиться.

Особенности составления документации

Стандартизация

Документация составляется не просто так, а в соответствии со стандартами, официально принятыми в местности обитания программиста. Или же в соответствии с международными нормами (ISO/IEC, «Единая система программной документации» — УСПД, ГОСТы в СНГ). Построение документа, размещение текста, графические элементы, примечания, приложения с таблицами и диаграммами — всё это имеет значение.

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

Ну а если всё оформлено в привычном виде, то вникнуть в суть сможет любой профессионал.

Автоматическая генерация из кода

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

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

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

Заключение

Да, а вы что думали, нередко на все эти бумажки уходит не меньше времени, чем на создание самой программы. Особенно если заказчик попадается страсть какой привередливый. С другой стороны, если смотреть на жизнь позитивно, эта работа ведь тоже оплачивается. Следовательно, освоить такую сторону деятельности всё же полезно.

Автор: vanilinkin, специально для xBB.uz, 06.11.2011


Предыдущие публикации:

Биржа долевых инвестиций SIMEX.

Последнее редактирование: 2011-10-06 12:05:04

Метки материала: документация, документация для программиста, программист, по, it, софт, разработка по, программирование, soft, программное обеспечение, информационные технологии, software, ит, программное обеспечение по


1 комментарий

30.11.2017 18:23:56 #
Google Chrome Гость Гена
Почему вы относите схемы БД и прочих систем к технической документации, если это обычно делается с помощью UML диаграмм?

Оставьте, пожалуйста, свой комментарий к публикации

Представиться как     Антибот:
   

Просьба не постить мусор. Если вы хотите потестить xBB, воспользуйтесь кнопкой предварительного просмотра на панели инструментов xBBEditor-а.


© 2007-2017, Дмитрий Скоробогатов.
Разрешается воспроизводить, распространять и/или изменять материалы сайта
в соответствии с условиями GNU Free Documentation License,
версии 1.2 или любой более поздней версии, опубликованной FSF,
если только иное не указано в самих материалах.