Я (наконец) читал о стандартах кодирования 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, очень мощный инструмент, который сокращает время, затрачиваемое на поиск старых объявлений функций. Аптана и 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. Это сэкономит вам огромное количество времени и разочарования. Такие вещи, как автоматическое указание начала и конца {}, () и т. Д.