2 просмотров
Рейтинг статьи
1 звезда2 звезды3 звезды4 звезды5 звезд
Загрузка...

Документирование PHP кода. DocBlock комментарии

Урок — Знакомство с документированием phpDoc

Комментарии – важная часть PHP кода. Комментарии должны быть:

  • Полными
  • Точными
  • Актуальным

PHPDoc (он же PHPDocumentor) — приложение(точнее скрипт) позволяющие генерировать документацию основанную на PHPDoc-комментариях. PHPDocumentor предложил формальный стандарт для комментирования PHP кода, который используется для автоматической генерации документации в HTML, man, RTF и XML, CHM, PostScript, PDF. Сайт PHPDoc.

PHPDoc-комментарий (или Doc-комментарий, илиDoc-блок) — специальный многострочный комментарий, информация из которого будет использоваться для формирования документации.

В php есть два вида комментариев:

  • // — однострочный коментарий.
  • /* .. */ — многострочный коментарий.

Однострочные комментарии имеет смысл оставлять внутри кода. Однострочне комментарии ставятся на строке перед комментируемым блоком кода.

Знакомство с PHPDoc

В основе работы phpdocumentor лежит разбор логической структуры PHP кода (классов, функций, переменных, констант) и привязка к ней комментариев, написанных по определенным стандартам.

Для начала приведем пример Doc-комментария:

Обратите внимание, что в начале идет /** наклонная черта и две звездочки. Это важно. Таким образом генераторы документации понимают, что далее идет DOC-комментарий а не просто комментарий заключенный в /* .. */

Хотя это и не обязательно, каждую строку в блоке комментариев /** . */ обычно начинают с сим­вола звездочки (*), иногда пробел и символ звездочки. В основном это делается для улучшения читаемости.

Внутри DOC-комментария некоторые слова приобретают дополнительное специальное значение. Такие слова называются тегами и начинаются с символа «@» (комерческое а). Пример нескольких тегов: @access, @author, @package, @param, @return, @since, @var, @version. Теги позволяют указать дополнительную информацию: какие параметры принимает функция и какого типа переменную она возвращает, но и связать комментарии и другие полезные данные с объектами, функциями и переменными.

В первой строке DOC-комментария дается краткое описание.

Если нужно дополнительное описание функционала — делается отступ в одну строку.

Читать еще:  М пришвин кладовое солнце. Пришвин михаил михайлович

Следующий раздел DOC-комментария (необязательно) — это более развернутое описание. Здесь необходимо описать комментируемый элемент с точки зрения их внешнего использования, — т.е. не как они устроен, а что кон­кретно делает. Подробные описания устройства должны вестись внутри кода, а не в DOC-комментарии.

Добавляем пустую строку и далее описание ведем с помощью PHPDoc-тегов.

PHPDoc-комментарии могут содержать HTML-разметку из тегов:

  • — жирное начертание;
  • — код;
  • — разрыв строки;
  • — курсив;
  • — сочетание клавиш;
  • — элемент списка;
    1. — нумерованный список;

PHPDoc-комментариями необходимо сопровождать:

  • Файлы
  • Классы
  • Свойства классов
  • Константы классов
  • Методы классов
  • Константы
  • Функции

Урок 6. PHP — Комментарии

Комментарии в PHP аналогичны комментариям, которые используются в HTML. В синтаксисе PHP комментарий начинаются всегда с особой последовательностью символов и весь текст, который появляется между этих спецсимволов, будет проигнорирован интерпретатором.

В HTML основная цель комментария в том, чтобы служить в качестве примечания разработчикам, которые могут просматривать исходный код вашего сайта. Комментарии РНР отличаются тем, что они не будут отображаться для посетителей. Единственный способ посмотреть PHP комментарии это открыть файл для редактирования. Это делает PHP комментарии полезными только для PHP — программистов.

В случае, если вы забыли или не знали, как делаются комментарии в HTML, то смотрите пример ниже.

Синтаксис php комментариев: однострочный комментарий

Тогда как в html есть только один вид комментариев, в PHP имеется целых два типа. Первый тип, который мы будем обсуждать, это однострочный комментарий. То есть комментарий, который говорит интерпретатору игнорировать все, что происходит на этой линии справа от комментариев. Для использования этого комментария следует применять символы «//» или «#» и весь текст справа будет игнорироваться интерпретатором PHP.

Обратите внимание на то, что несколько наших команд echo не были обработаны, потому что мы закомментировали их с помощью специальных символов комментирования. Этот тип комментариев часто используется для быстрой записи о сложном и запутанном коде или чтобы временно удалить строку кода PHP (для отладки).

Синтаксис php комментариев: многострочный комментарий

Как и HTML — комментарии, многострочные комментарии в PHP могут быть использованы для комментирования больших блоков кода или для записи комментов в несколько строк. Многострочные комментарии в PHP начинается с «/*» и заканчиваются «*/». Все, что находится между этими символами, будет игнорироваться.

Комментирование кода — это хорошо!

Комментирование это то, что я могу порекомендовать всем начинающим программистам РНР. Комментируйте свой код! Так много людей пишут сложный код на PHP и либо слишком ленивы, чтобы писать хорошие комментарии или считают, что комментарии не нужны. Тем не менее, вы действительно верите, что вы сможете вспомнить, что именно вы думали, когда писали этот код год или более назад?

Пишите комментарии сегодня и вы скажете себе за это спасибо в будущем! 🙂 Поставить два слеша и черкануть пару слов о коде не составит большого труда, зато очень пригодится, когда вы к нему вернетесь через некоторое время!

Комментарии:

  1. Миша — 04.03.2013 12:47

Да, комментировать код очень важно, абсолютно согласен с автором!

Сергей — 25.03.2013 21:46

Всё понял как делать но чета не выводиться у меня даже текст в файле индекс.пхп больше ни чего, в этой же папке текст в файле мену.пхп

Сергей, я, если честно, ничего не понял) Что не выводится и куда? Комментарии и не должны выводиться — они видны только в исходном коде страницы.

Стас — 28.02.2017 13:55

Еще легче так это поставить скрипт готовых комментариев на сайт типа disqus

Виталий — 23.05.2017 13:30

Стас, ору с тебя)) причем тут дискус? Речь не о комментировании на сайте, а о комментировании кусков, блоков или строк кода на PHP — чтоб потом самому ж легче было понимать, что написал, и если кто другой читать код будет то тоже чтобы более проще было)

Комментирование кода PHP

Комментарии в PHP при выполнении скрипта игнорируются препроцессором, и нужны только для людей. Разработчики часто пренебрегают комментированием кода.

Среди программистов бытует мнение, что они вспомнят, как работает код, и через шесть месяцев и через год. Еще одна причина не оставлять комментарии — уверенность в том, что код настолько хорошо написан, что он ясен и без пояснений. Но нужно помнить, что может потребоваться продолжать поддерживать созданные скрипты PHP долгое время после написания.

Не менее важная причина комментирования кода — убедиться, что последователи поддерживают или добавляют функциональность вашему творению. Они также получат пользу от чтения оставленных комментариев.

PHP предоставляет два способа комментирования: один — для однострочных комментариев, а второй — для многострочных. PHP заимствует синтаксис комментариев из C , C++ и Java . Так что, если вы знакомы с ними, то сюрпризов для вас не будет.

Однострочные комментарии PHP

Перед комментариями, которые находятся на одной строке, в PHP ставятся два символа косой черты ( // ).

Следующий пример содержит однострочный PHP комментарий в коде:

Однострочный комментарий может находиться на отдельной строке, или добавляется в конец строки кода:

В примере, приведенном выше, препроцессор PHP выполнит функцию echo и проигнорирует все, что расположено после // .

Однострочные комментарии также применяются, чтобы временно убрать строки кода из потока выполнения. Например, следующее изменение предыдущего примера приведет к тому, что PHP проигнорирует всю команду echo во время выполнения:

Многострочные комментарии PHP

Многострочные комментарии для сайта PHP обернуты разделителями / * и * /. Знак /* обозначает начало блока комментариев, а */ указывает на его конец. Следующий пример демонстрирует использование многострочного комментирования:

Многострочные комментарии полезны, когда заметки, которые вы хотите вставить в код, занимают более одной строки. Возможность помечать блоки строк как комментарии позволяет избежать использования однострочного комментария в начале каждой строки.

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

Итоги

И однострочные, и многострочные комментарии можно легко добавить в PHP- код , используя специальный синтаксис. Постарайтесь выработать привычку комментировать свой код.

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

Данная публикация представляет собой перевод статьи « Commenting PHP Code » , подготовленной дружной командой проекта Интернет-технологии.ру

Источники:

http://ramech.net/courses/phpdoc/overview.html
http://myblaze.ru/urok-6-php-kommentarii/
http://www.internet-technologies.ru/articles/kommentirovanie-koda-php.html

Ссылка на основную публикацию
Статьи c упоминанием слов:

Adblock
detector