В этой статье вы узнаете, как создавать комментарии в скрипте PHP, и посмотрите на некоторые примеры комментирования, а также получите советы, как эффективно писать и форматировать комментарии. Вы также узнаете, как использовать комментарии для «комментирования» фрагментов кода PHP.

Как и большинство языков программирования, PHP позволяет добавлять комментарии к вашему коду. Комментарии - это фрагменты кода, которые игнорируются, когда код запускается механизмом обработки PHP. При помощи комментирования можно для себя либо других программистов оставлять комментарии к коду.

Создание PHP-комментариев.

Существует два основных типа комментариев PHP:
1. Однострочный комментарий. Это короткий комментарий в одной строке кода.
2. Многострочный комментарий. Это более длинный комментарий, который может растягиваться на несколько строк.

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

Чтобы закомментировать строку либо добавить комментарий к строке, необходимо перед комментарием поместите либо // (2 слэша), либо # (хеш).
Примеры однострочного комментирования:
1. Комментирование строки (когда вся строка становиться "невидимой" для PHP-обработчика)

<?php
// Строка ниже выведет на экран Здравствуй, Мир!
echo "Здравствуй, Мир!";
# Строка ниже выведет на экран Ура, я работаю:)
echo "Ура, я работаю:)";
?>

2. Добавления комментария к строке (когда после знаков комментирования, PHP-обработчик перестаёт обрабатывать строку, т.е. всё, что будет стоять после символов комментирования, PHP-обработчик посчитает за комментарий.

<?php
echo "Здравствуй, Мир!"; // выведет на экран Здравствуй, Мир!
echo "Ура, я работаю:)"; # Строка ниже выведет на экран Ура, я работаю:)
?>

Как правило комментирование при помощи // (2 слэша), более популярно среди программистов PHP, однако оба способа комментирования (при помощи слэшей и хеша) являются правильным, и не создают проблем при обработке PHP кода.

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

Иногда однострочного комментария бывает недостаточно, например, когда вы хотите закомментировать несколько строк кода, либо ваш комментарий слишком длинный. Конечно, можно воспользоваться однострочным комментированием, и каждую строку комментировать, но это долго и не очень продуктивно. Ещё одним из плюсов данного способа комментирования является то, что после окончания знаков комментирования PHP-обработчик продолжит обрабатывать код в строке, т.е. данным способ более универсален, чем однострочное комментирование, которое прекращает обработку строки.

Чтобы закомментировать несколько строк кода или добавить комментарий в середине строки с кодом, необходимо воспользоваться /* (слэш, за которой следует звездочка) и завершить комментарий с помощью */ (звездочка, за которой следует слэш).

Рассмотрим несколько примеров PHP-комментирования при помощи слэша и звёздочки:

<?php
	/*
 	Здесь может быть многострочный комментарий. Например с указанием своих данных:
	
	Автор: Дмитрий быков
	Web-site: https://dbykov.ru
	E-mail: mail@dbykov.ru
	*/
	$text=" Ура, я работаю:)";
	echo "Здравствуй, Мир!".$text." Спасибо!!";
?>

В результате выполнения этого кода, пользователю на экране выведется надпись: Здравствуй, Мир! Ура, я работаю:) Спасибо!! Это пример многострочного комментария, а сейчас рассмотрим пример комментирования с помощью конструкции /* */ (слэш звёздочка звёздочка слэш) в строке, надо иметь ввиду, что внутристрочные комментарии практически нигде не используются, но о них всё равно стоит знать:

<?php
	$text="Ура, я работаю:)";
	echo "Здравствуй, Мир!"./*$text.*/" Спасибо!!";
?>

В результате выполнения этого кода, пользователю на экране выведется надпись:

Здравствуй, Мир! Спасибо!!

Как вы видите комментирование с помощью слэша со звездочкой очень функционально, но стоит обратить внимание на то, что нельзя внутри многострочного комментария размещать ещё один многострочный комментарий!

<?php
	/*
 	Здесь может быть многострочный комментарий. Например с указанием своих данных:
	
	Автор: Дмитрий быков
	Web-site: https://dbykov.ru
	E-mail: mail@dbykov.ru
	/*
	$text=" Ура, я работаю:)";
	*/
	echo "Здравствуй, Мир!".$text;
	*/
?>

Как вы видите тут используется двойной комментарий, но данный код начнёт обрабатываться с отрезка, впервые найденных символов, закрывающих комментирование (*/). Поэтому при разработке веб-приложений рекомендуется использовать редакторы с функцией подсветки синтаксиса PHP-кода.

Комментирование в PHP - хорошая черта разработчика.

Очень важно прокомментировать ваш PHP-код. Обычно, когда программист пишет PHP-скрипт, его код кажется осмысленным и понятным, но через некоторое время, когда он к нему вернётся, без комментариев к коду, программисту потребуется продолжительное время, что бы вспомнить свой же код. Если вы добавляете комментарии во время написания кода, то ваш код будет намного читабельнее, и, когда вы (или другой разработчик) вернетесь к нему, сможете в разы быстрее понять логику его работы.

Хорошие комментарии объясняют, что делает тот или иной кусок кода. Лучше всего, писать свои комментарии перед куском кода. Это заставляет вас думать о том, что должен делать код.

В этой статье вы узнали, как писать комментарии PHP (однострочные, многострочные и внутристрочные), рассмотрели, как форматировать комментарии и как «комментировать» фрагменты кода PHP.

Желаю вам успехов в комментировании PHP-кода!