PHP, Управление проектамиНесколько слов о документировании

Данная статья является авторским вольным переводом
оригинальной статьи Эли Уайта (Eli White).

Всем известна стандартная мантра программирования «Документируй свой код!» (хотя некоторые разработчики, как оказывается, все еще не следуют ей). Именно поэтому мы сегодня поговорим о трех видах документации, которые могут быть созданы для проекта, и почему каждая из них имеет такое важное значение.

Первое, что приходит на ум PHP-программисту, как только речь заходит о документировании кода — это PHP DocBlocks.

DocBlocks — это система для обеспечения последовательности в ваших комментариях и благодатная почва для автоматического создания документации. К тому же, DocBlock, по своей природе, основан на принципах документирования API конкретных функций, классов и т.д., и в этом плане — это превосходная, очень удобная система.

Проблема же заключается в том, что документирование API-функций и их параметров, а также классов, и других аналогичных вещей — это только один из трех важных типов документации, которые необходимы. В реальности же, слишком много PHP программистов ограничиваются лишь написанием DocBlock'ов, и считают, что их требования по документированию кода полностью выполнены.

Но это далеко от истины.

Во-первых, в рамках достаточно крупного проекта есть и более высокоуровневые формы той документации, которая необходима. За неимением лучшего термина, назовем ее «описанием реализации». В принципе, то, о чем идет речь — это не просто документ, который гласит: «Вот это такой-то класс, который можно так-то использовать; у него есть такие-то методы». В общем случае это также объясняет как, в рамках вашего проекта, данные классы могут быть использованы.

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

Следующий тип документации, о котором программисты, как правило, забывают наиболее часто, наступая на грабли под именем DocBlock — это старые добрые встроенные (inline) комментарии.

Встроенные комментарии объясняют, что и как делают те или иные фактические строки или блоки кода, что абсолютно важно для того, чтобы другие программисты смогли понять чужой код и модифицировать его. Да, вы можете думать, что ваша функция из 10 строк настолько проста, что любой ваш последователь сможет легко понять ее, но следует учитывать, что довольно часто ваши соотечественники программисты не будут планировать в полной мере осознать все аспекты данной функции, для того, чтобы исправить ошибку в ней. Хорошие комментарии, которые объясняют, что делают различные блоки кода, имеют абсолютно решающее значение для быстрой отладки — они позволяют программисту быстрее найти необходимый блок кода, без чтения и понимания каждой его строки.

Каждый, разумеется, имеет свое собственное видение как и сколько встроенных комментариев следует писать, и скорее всего, однозначный ответ на данный вопрос попросту отсутствует. Это скорее всего, должно определяться требованиями к проекту. Ходят слухи, что иногда программисты сталкиваются с требованиями в необходимости писать одну строку комментариев для каждой строки кода. Далее такой подход может быть использован для создания ПО, которое удалит все фактические строки кода, оставив только комментарии, для того, чтобы люди смогли прочитать, что код должен был делать на обычном русском (английском, французском и др.) языке.

Одна строка комментария на каждую строку кода, пожалуй, выход за пределы разумного.

В целом, можно руководствоваться следующими принципами для хорошего документирования кода:

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

Таким образом, мы надеемся, что вы с пользой прошлись по этой краткой заметке о документировании кода. Используете ли вы PHP DocBlocks или нет, попробуйте сделать так, чтобы убедиться, что вы смогли охватить все три аспекта документирования вашего проекта:

  • «Описание реализации» — рассказывает о том, с чего программисту следует начать для выполнения задачи, и как все устроено на высоком уровне.
  • Документация API, которая описывает каждый класс и функции в деталях.
  • Встроенные комментарии, которые описывают сам код.

Удачи в девелопменте!

Хорошая статьяПлохая статья +9
   |    Опубликовано: Декабрь, 25 2008г.    |    Автор: Михаил Стадник

Комментарии (3) к статье “Несколько слов о документировании”

Оставить комментарий