5. Документирование разработки.
5.1. Общие положения.
Прежде, чем говорить о структуре отчёта и правилах его построения, нужно сказать ещё об одной немаловажной функции - это взаимодействие с партнёром по работе над проектом. Бесспорно, что современное программное обеспечение разрабатывается коллективами. Коллективы могут быть большими, маленькими, но не зависимо от размера, важнейшим компонентом работы будет взаимодействие между членами коллектива. Взаимодействие заключается в передаче информации о своей работе, о том как устроен изготовляемый модуль, какие ему для работы требуются данные, что он даёт на выходе, какие имеются особенности его работы. То есть программист, работающей в команде, должен уметь прозрачно и точно описать свою разработку, являющуюся частью большого целого. Таким образом, написание отчёта - это тренировка взаимодействия внутри группы разработчиков.
5.2. Технология составления отчёта:
5.2.1. Содержание отчёта
Отчёт содержит в себе основную информацию, которая помогает пониманию программы. Стандартная форма. отчёта содержит следующие пункты:
Описание задачи: что требуется; какие имеются данные; какие требования предъявляются к решению.
Описание идеи решения и алгоритма.
Описание структур данных, если в программе используется много данных или есть сложные структуры данных. Например, такое описание является обязательным, если речь идёт о задаче разработки базы данных.
Возможно, в программе используются сложные приёмы для решения частных проблем, и эти приёмы оформлены в виде отдельных, логически завершенных модулей. Эти приёмы следует описать отдельно.
Если в программе или алгоритме существуют очень маленькие блоки, может быть даже состоящие из одной команды, выполняющие сложное действие, то такие блоки желательно пояснять примечаниями.
Отдельно следует обратить внимание на второй пункт: описание алгоритма. Если программа состоит из отдельных логически законченных блоков, и эти блоки оформлены в виде процедур или функций, то описание может состоять из перечня описаний процедур и функций, для каждой из которых следует описывать данные, которые она получает на входе и данные являющиеся результатом работы. Кстати результатом работы могут быть не только данные, но и состояние экрана, состояние некоторых файлов и т.д.
5.2.2. Общие требования, предъявляемые к отчёту:
Описание алгоритма должно строго соответствовать тексту программы. При всей очевидности требования, оно далеко не всегда выполняется. Причина этому та, что многое выполняется интуитивно. Для того, чтобы выполнить поставленное требование, необходимо вывести все свои интуитивные выкладки на уровень сознания – алгоритма = диаграммы состояний программы.
Все используемые термины и понятия должны быть прозрачны. При этом необходимо учесть, что очевидное для автора разработки может отличаться от очевидного с точки зрения соседа. Выполнение данного требования помогает прочувствовать свойство алгоритмов быть однозначно определёнными, и то насколько естественный язык не соответствует данному алгоритмическому требованию.
Детализация алгоритма должна быть достаточной, а не максимально глубокой. Существует некоторый уровень детальности, на котором уже всем всё понятно. Однако необходимо помнить, что уровень детальности меняется относительно некоторого среднего интеллектуального уровня. Профессионалу программисту для понимания относительно небольшой программы достаточно условия задачи и текста программы, начинающему нужно описание алгоритма. Таким образом, уровень детальности, на котором описывается свою разработка, является индикатором его знаний и умений автора.
Из отчёта обязательно должно быть видно, как изменяются данные в процессе работы программы. Если эти изменения не описаны, то видимо автор не в состоянии представить себе процесса работы программы. Это в свою очередь означает, что программа для него что-то статичное, оторванное от исполнителя. Данное понимание программы глубоко ошибочное и подлежит исправлению.