При разработке сложной системы значительная часть времени
уходит на поиск данных, уже сформированных кем-то из группы
разработчиков или привнесённых в группу извне, а значительная
часть ошибок возникает из-за того, что эти данные не найдены или
неверно интерпретированы, либо из-за того, что не пришла в голову
мысль, что они уже где-то есть. Чтобы минимизировать подобные
потери, следует устанавливать и жёсткими мерами поддерживать на
проекте развитую и чёткую систему документирования и информацион-
ного взаимодействия. Такая система в значительной степени универ-
сальная, и особенности конкретного проекта требуют изменения её
только в малой части.
Качество документации на проекте должно быть адекватно уровню
сложности этого проекта, иначе проект превратится из сложного в
сверхсложный и, если не застопорится совершенно, то значительно
сбавит темп продвижения вперёд.
Работа над проектом должна начинаться с разворачивания системы
документации -- существующей вначале в виде совокупности пустых
"ёмкостей", которые будут постепенно заполняться данными.
Любое изменение в разрабатываемой, развиваемой, поддерживаемой
программной системе должно сопровождаться соответствующим измене-
нием в документации на систему. Если это правило хотя бы иногда
нарушается, документация оказывается всё менее адекватной
системе, из-за чего использование этой документации становится
причиной ошибок.
* * *
Все сложные решения должны документироваться. В том числе
должны фиксироваться основания для принятия этих решений. Также
должны кратко помечаться отброшенные варианты и их недостатки.
В противном случае через некоторое время будет трудно вспомнить
причины того или иного выбора, будет тратиться на это время, и
будет риск возвращения к тому, что в своё время оказалось на
правильных основаниях отвергнутым.
Должны документироваться, среди прочего, решения, принимаемые
отдельными специалистами в пределах их компетенции -- не требую-
щие согласования с кем-либо.
Через такое документирование достигается, среди прочего, взаи-
мозаменяемость участников проекта, и руководитель проекта оказы-
вается лучше защищён от возможных капризов отдельных работников.
* * *
Система документации должна выстраиваться по принципу минималь-
ного разнообразия оформления и языка.
Надо различать архитектуру системы документации и техническую
реализацию этой архитектуры в виде электронных документов, под-
держиваемых программными средствами определённых типов на техни-
ческих устройствах определённых типов.
Документы разделяются, среди прочего, на основные и производ-
ные. Производные документы содержат данные из основных, представ-
ленные в форме, которая более удобна для выполнения некоторой
работы. Они дублируют сведения, но это дублирование является
источником эффективности. Пренебрежение возможностью создания
таких документов под тем предлогом, что сведения уже где-то
зафиксированы, приводит к потере времени.
* * *
Система документации -- совокупность документов на техническую
систему, выполненных в едином стиле и связанных взаимными
ссылками.
Прототип системы документации -- полный набор заготовок доку-
ментов на систему и на проект её разработки: с оглавлениями,
стандартными элементами содержания, вставленными подсказками по
заполнению. Прототип включает в себя заготовки не только выходных
документов, но также и промежуточных (внутренних). Он представля-
ет собой сложное изделие -- предмет самостоятельной разработки и
возможный товар для широкой продажи.
Прототипы систем документации могут различаться между собой
тем, что ориентируются на документируемые системы разных типов и
разных уровней сложности, на разное техническое обеспечение
документирования. Они могут также различаться стилем оформления.
Когда начинается программный проект, для него должен быть вы-
бран наиболее подходящий прототип системы документации -- по ана-
логии с тем, как должен быть выбран прототип для разрабатываемой
программной системы.
Система документирования -- это набор инструментов для разра-
ботки и поддержания системы документации.
* * *
При разработке сложной технической системы документацию к ней
лучше упорядочивать по иерархическому принципу. В этом случае
основным документом является список других документов, относящих-
ся к разработке системы, с указанием 1) их типа, 2) даты их ак-
туальной версии, 3) прав доступа к ним, 4) мест их расположения.
Если заранее неизвестно, где отыскать те или иные данные, поиск
начинается с обращения к этому списку. Через него обеспечивается
ЦЕЛОСТНОСТЬ системы документирования.
Те или иные сведения о программной системе должны не просто
присутствовать в документации, выражаться в программном коде или
в комментариях к нему: эти сведения должны быть ЛЕГКОДОСТУПНЫМИ
на основе простой стратегии поиска, иначе решение различных
проблем в системе будет дополнительно отягощаться проблемой
поиска нужных данных.
Причины плохого документирования системы:
1) непонимание значимости документации (следствие упрощённости
представлений о технологии разработки сложных систем);
2) стремление облегчить текущую работу в ущерб будущей работе;
3) надежда на собственную память;
4) неспособность к написанию внятных текстов;
5) нежелание делиться сведениями с коллегами (следствие стремле-
ния обеспечить собственную незаменимость).
Люди с хорошей памятью более склонны пренебрегать документиро-
ванию, чем люди с плохой памятью, и способны в конечном счёте
если не застопорить сложный проект, то сделать его сверхсложным,
так что разбираться в нём смогут лишь им подобные, да и то ценой
больших затрат времени.
Оставлять написание исчерпывающей и качественной документации
напоследок, на тот период, когда проектные решения в основном уже
устоятся, значит существенно затруднять выработку и корректировку
проектных решений.
Надо твёрдо устанавливать, в каких своих частях разрабатываемая
программная система является документируемой и в каких -- самодо-
кументируемой, то есть понятной на основе её кода и комментариев
к нему.
* * *
Документы могут представлять собой наборы данных (файлы),
находящиеся в некоторой области на сервере или "мэйнфрейме",
доступной для всех участников проекта.
!MAIN -- Main document: список других документов;
CODING -- Coding rules;
DECISIOS -- Decisions: основные решения по проекту;
DICTIONR -- Dictionary;
ENVIRONM -- Environments;
FUNCTIS -- Functions;
INCLUDES -- Includes;
INSTRUMS -- Instruments;
LIBRARIS -- Libraries;
MESSAGES -- Messages of the system;
MODULS -- Moduls;
NAMING -- Naming rules;
NEWS -- News: новости на проекте;
PERSONS -- Persons;
REPORTS -- Personal weekly reports
ROLES -- Roles;
SCREENS -- Screens;
SUBJECT -- Subject area descriptions;
TESTCAS -- Testcases;
USERIDS -- UserIDs;
Содержанием документов этого списка может быть набор конечных
данных или список других документов.
* * *
Группы документов:
отношения с заказчиком;
архитектура;
техническая реализация;
тестирование;
инструкции пользователям;
инструкции по установке;
инструкции по поддержке;
планы;
отчёты;
соглашения по сопряжению;
описания используемых инструментальных средств;
описания сопрягаемых систем.
* * *
Важная часть документации -- таблицы соответствий между различ-
ными компонентами программной системы, проекта. Если установлены
эффективные правила именования компонентов, потребность в таких
таблицах уменьшается, но не устраняется полностью. Могут исполь-
зоваться, к примеру, следующие таблицы соответствий:
экраны -> программы, работающие с этими экранами;
программы -> таблицы баз данных, к которым эти программы
обращаются;
функции -> головные программы, реализующие эти функции;
программы -> разработчики этих программ;
задания на создание таблиц базы данных -> таблицы базы
данных, создаваемые этими заданиями.
...............................................................
...............................................................
Александр Бурьяк.
