Я (наконец-то) читал о стандартах кодирования 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, чтобы выполнить АОП. , выполняя проверку DocBlock над вашими объявлениями во время выполнения. Фактически, Doctrine использует его для построения карты атрибутов объекта для их реализации «Active Record».
Комментарий с двойной звездочкой иногда используется некоторыми системами документации. Система документации будет обрабатывать блок и искать определенные ключевые слова, такие как @author или @var.
Комментарии с одной звездочкой будут рассматриваться как // комментарии.
См. PhpDoc http://www.phpdoc.org/docs/latest/guides/types.html
Я согласен с Айоном и Квентином. В основном это читабельность. Однако есть еще одна вещь.
Существуют автоматические генераторы документации (например, doxygen).
Они требуют особого форматирования комментариев, чтобы включить эти комментарии в документацию. Я считаю, что этот стиль комментирования используется именно для этой цели (посмотрите следующую страницу документации doxygen - http://www.doxygen.nl/manual/docblocks.html)
Читаемость.
Он четко выделяет закомментированный раздел для людей, читающих код.
Я думаю, что это в основном только для внешнего вида/удобочитаемости. Представьте, что у вас есть очень длинный раздел комментариев, выходящий за пределы одного экрана. Затем, увидев эти звездочки, вы узнаете, что это часть комментария, даже если вы не видите начала и конца.
Если вы используете отличный бесплатный текстовый редактор jEdit для редактирования вашего PHP, он выделяет код разными цветами, чтобы показать, что такое глагол, что такое переменная и т. д.
Если вы закомментируете блок с помощью /* ... */, все внутри блока станет оранжевым, что затруднит чтение кода.
Если вместо этого вы закомментируете его с помощью /** ... */, то он изменит все в блоке на другой набор цветов, которые по-прежнему выделяют разные части кода, что означает, что код остается очень читаемым.
PS. Если вы используете Блокнот или что-то подобное для редактирования кода PHP, я настоятельно рекомендую вам установить jEdit. Это сэкономит вам огромное количество времени и нервов. Такие вещи, как автоматическое указание начала и конца { } , ( ) и т. д.
