Я (наконец) читал по стандартам кодирования PEAR (php).
Какова цель комментирования следующим образом:
/**
* Here is my comment
* I Wrote this in a haiku
* But why put the stars?
*/
В противоположность этому:
/*
Here is a comment
No haiku or
anything special, but it still works!
*/
Документ /** stuff */ также упоминается как DocBlock.
Он использовал для документирования функций PHP, классов и т.д.
/**
* A test function
*
* @param foo $bar
* @return baz
*/
function test(foo $bar) { return new baz; }
Некоторые редакторы хорошо используют это, чтобы выполнить свою функцию Code Insight, очень мощный инструмент, который сокращает время, затрачиваемое на поиск старых объявлений функций. У Aptana и Zend Studio есть эта функция, возможно, и другие.
Вы также можете использовать его в сочетании с Reflection, чтобы сделать какой-то AOP, выполняя проверку выполнения DocBlock во время выполнения над вашими объявлениями. Фактически, Doctrine использует его для создания атрибута атрибута объекта для своей реализации "Active Record".
Я согласен с аджоном и Квентином. В основном это читаемость. Однако есть еще одна вещь.
Существуют генераторы автоматической документации (например, doxygen).
Они требуют некоторого форматирования комментариев для включения этих комментариев в документацию. Я считаю, что этот стиль комментариев используется именно для этой цели (см. Следующую страницу документации для кислорода) http://www.stack.nl/~dimitri/doxygen/docblocks.html)
Комментарий двойной звездочки используется когда-то некоторыми системами документации. Система документации будет выполнять блок и искать определенные ключевые слова, такие как @author или @var.
Отдельные комментарии звездочки wil рассматриваются как комментарии //.
См. PhpDoc http://www.phpdoc.org/docs/latest/guides/types.html
читаемости.
Он четко выделяет комментарий для людей, читающих код.
Я думаю, что это в основном просто для внешнего вида/удобочитаемости. Представьте, что у вас очень длинный раздел комментариев, который выходит за рамки одного экрана. Затем, увидев эти звездочки, вы узнаете, что это часть комментария, даже если вы не можете видеть начало и конец.
Если вы используете отличный текстовый редактор jEdit для редактирования своего PHP, он выделяет код разных цветов, чтобы показать, что такое глагол, что такое переменная и т.д.
Если вы закомментируете блок с /*... */все внутри блока идет оранжевым, что затрудняет чтение кода.
Если вы вместо этого прокомментируете это с помощью /**... */, то он изменяет все в блоке на другой набор цветов, которые все еще выделяют разные части кода, то есть код остается очень читаемым.
PS. Если вы используете Блокнот или аналогичный для редактирования своего PHP-кода, я настоятельно рекомендую вам получить jEdit. Это сэкономит вам огромное количество времени и разочарования. Такие вещи, как автоматическое указание начала и конца {},() и т.д.