3 аспекта документирования

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

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