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

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

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

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

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

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

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

<?php

     // Это однострочный комментарий

?>

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

<?php

    echo "Это проверочная строка"; // Вывести строку текста

?>

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

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

<?php

    // echo "Это проверочная строка";

?>

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

<?pre

/*
   Это многострочный блок 
   комментариев
*/

?>

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

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

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

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

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

www.internet-technologies.ru

Комментарии в php коде и как закомментировать код. Основы PHP с нуля. Урок №4

Главная » Основы PHP » Комментарии в php коде и как закомментировать код. Основы PHP с нуля. Урок №4

Комментарии в php коде и как закомментировать код. Основы PHP с нуля. Урок №4

Всем привет!

Продолжаем изучать основы PHP с нуля!
В этом уроке я расскажу, что такое комментарий в PHP и на практике попробуем прописать в коде свой комментарий. Но это еще не все. Еще хочу рассказать, как закомментировать код и для чего это вообще нужно делать.

Начнем!

Что такое комментарий в PHP
Комментарий в PHP – это подсказка php-разработчика для быстрого ориентирования в коде, а также для правок.

Комментарий в PHP невиден для пользователя, который открыл веб-страницу для просмотра. Даже если пользователь надумается посмотреть исходный код страницы, комментарий все равно виден не будет, так как и весь код php.

PHP комментарий коде

Существует 2 вида комментариев для кода PHP:

→ однострочный
→ многострочный

⇒ Однострочный комментарий для PHP
Для однострочного комментария следует применять символы «//» или «#»

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

Пример:


<?php
// Однострочный комментарий для PHP
# Однострочный комментарий для PHP (можно и так)
echo "Привет читателям блога - StepkinBLOG.RU!!!"; // Мое приветствие (это комментарий)
echo "<br />Подпишись на обновление"; # подписка (это комментарий)
?>

На экране вы только увидите вот такой текст:

Привет читателям блога — StepkinBLOG.RU!!!
Подпишись на обновление

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

Пример:


<?php
/*
Многострочный комментарий для PHP.
Многострочный комментарий используется,
если в записи несколько строк.
*/
echo "Привет читателям блога - StepkinBLOG.RU!!!";
?>

На экране вы только увидите вот такой текст:

Привет читателям блога — StepkinBLOG.RU!!!

P.S.: Всегда комментируйте свой код. Если вы считаете, что вспомните все, что делали в коде через 1-2 года, вы ошибаетесь, шанс очень маленький. Даже если и вспомните, то придется потратить кучу времени на изучение – что, куда и зачем…
Сделайте приятное для себя будущего – закомментируй код и ты сам себе потом скажешь «СПАСИБО!!!».
Оставь комментарий в коде, это займет 1 минуту времени, но сэкономит тебе в будущем целый день.

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

Припустим, вы написали php код, но по каким-то причинам вам нужно удалить из кода 2 строки.

Я не спешу удалять что-то из кода, особенно, если это php-код, я лучше его закомментирую. А вдруг нужно будет код вернуть. Легче же разкомментировать, чем по-новому писать код.

Как закомментировать код в PHP
Пример с однострочным комментарием:


<?php
// echo "Привет читателям блога - StepkinBLOG.RU!!!";
// echo "<br />Подпишись на обновление";
?>

Пример с многострочным комментарием:


<?php
/*
echo "Привет читателям блога - StepkinBLOG.RU!!!";
echo "<br />Подпишись на обновление";
*/
?>

В результате, вы увидите пустую страницу .

P.S.: Не спешите удалять какой-то кусок кода. Сегодня может он и не нужен будет, а завтра, возможно, придётся код дописывать .

На сегодня все!
Подписывайтесь на обновления блога, если не хотите пропустить уроки по основам PHP! 

Предыдущая запись
Установка локального сервера на компьютер. Основы PHP с нуля. Урок №3 Следующая запись
Переменные в php. Основы PHP с нуля. Урок №5

stepkinblog.ru

Как закомментировать код CSS, HTML, JavaScript или PHP

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

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

/* Закомментированный код */

Примеры:

КОММЕНТИРОВАТЬ КОД В CSS

КОММЕНТИРОВАТЬ КОД В CSS

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

<!— Закомментированный код —>

Примеры:

КОММЕНТИРОВАТЬ КОД В HTML

КОММЕНТИРОВАТЬ КОД В HTML

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

// Закомментированный код

/* Закомментированный код */

Примеры:

КОММЕНТИРОВАТЬ КОД В JAVASCRIPT

КОММЕНТИРОВАТЬ КОД В JAVASCRIPT

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

// Закомментированный код

/* Закомментированный код */

Примеры:

КОММЕНТИРОВАТЬ КОД В PHP

КОММЕНТИРОВАТЬ КОД В PHP

Надо отметить, что двойной слеш // комментирует только строку.

Если использовать специальный редактор Notepad ++, тогда закомментированный код окрасится в зеленый цвет. Это очень удобно!

На заметку: JavaScript — независимый язык программирования, со своей спецификацией ECMAScript, и к Java не имеет никакого отношения.

Всем удачи и добра!

epicblog.net

php — Как закомментировать PHP код в HTML файлы выборочно?

Я пытаюсь сделать смешанный источник PHP / HTML файлов готов для перевода в OmegaT , которая является приложением перевода памяти Java. Он имеет HTML — фильтр , который может иметь дело с чистыми HTML файлы красиво, но запутывается , когда PHP код смешивается.

Чтобы избежать этой проблемы, я пытаюсь придумать решение поместить PHP код внутри комментариев HTML (<! — ->), так OmegaT HTML фильтр может игнорировать его.

Дальнейшее осложнение состоит в том, что комментирование должно произойти только тогда, когда код PHP находится между HTML-тегами и не тогда, когда код PHP используется для создания HTML атрибутов тегов.

Для того, чтобы проиллюстрировать требования лучше, я хотел бы добавить HTML комментарии по PHP кода в сНу ид = 1 и ид = 3, но в ид = 2.

Оригинал:

    <body>
      <div id=1>
        <?php
          echo $var;
        ?>
      </div>
      <div id=2>
        <a href=/index.php?p=<?php echo $var; ?> >text</a>
      </div>
      <div id=3>
        <p>Some text <?php echo $var; ?> generated partially with PHP.</p>
      </div>
    </body>

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

    <body>
      <div id=1>
        <!--<?php
          echo $var;
        ?>-->
      </div>
      <div id=2>
        <a href=/index.php?p=<?php echo $var; ?> >text</a>
      </div>
      <div id=3>
        <p>Some text <!--<?php echo $var; ?>--> generated partially with PHP.</p>
      </div>
    </body>

Если я закомментируйте PHP код в сНу ид = 2 фильтр OmegaT HTML преобразует <> символы в HTML-элементов, которые я хотел бы избежать.

Я пытался сделать простой скрипт на Perl, чтобы добавить комментарии, когда это необходимо, но я не смог придумать полезным решением заменителя регулярного выражения.

ru.coredump.biz

Как я должен закомментировать этот код?

Чтобы закомментировать любой HTML, независимо от того, встроен ли в него PHP или нет, все, что нужно, это HTML-комментарии «! -» и «-», как показано ниже:

 <!--div data-product="<?php $id = "293";
echo $id; ?>">PRICE AND AVAILABILITY</div-->

Если вы просматриваете страницу, содержащую этот бит HTML, вы не увидите эту строку. Если вы выполняете просмотр источника страницы, вы можете заметить, что код PHP действительно был обработан. Чтобы избежать выполнения PHP-кода, вы можете использовать PHP-комментарии как «/ * * /» или «//» следующим образом:

<!--div data-product="<?php /*$id = "293";
echo $id;*/ ?>">PRICE AND AVAILABILITY</div-->


<!--div data-product="<?php //$id = "293";
echo $id; ?>">PRICE AND AVAILABILITY</div-->

Еще один способ, который использует HTML «!» для предотвращения выполнения кода PHP:

<!--div data-product="<!--?php /*$id = "293";
echo $id;*/ ?>">PRICE AND AVAILABILITY</div-->

Недостаток HTML-комментария заключается в том, что его необходимо удалить перед завершением страницы, в противном случае пользователь испытывает неудобство при загрузке посторонних данных. Техника, упомянутая в двух других примерах использования тегов PHP с комментариями, позволяет избежать навязывания пользователю и не раскрывает то, что было закомментировано.

Связанное обсуждение демонстрирует изящный способ использовать PHP для комментирования HTML или HTML, встроенного в PHP, и позволяет впоследствии легко отменить комментирование кода следующим образом:

<?php /* ?>
 <div data-product="<?php $id = "293";
    echo $id; ?>">PRICE AND AVAILABILITY</div>
<?php // */ ?>

Позже можно оперативно удалить комментарий, изменив открывающий тег PHP следующим образом:

<?php //* ?>

Посмотреть демо

geekquestion.com

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

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

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

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


<!-- This is an HTML Comment -->

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

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


<?php
echo "Hello World!"; // This will print out Hello World!
echo "<br />Psst...You can't see my PHP comments!"; // echo "nothing";
// echo "My name is Humperdinkle!";
# echo "I don't do anything either";
?>

Результат:


Hello World!
Psst...You can't see my PHP comments!

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

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

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


<?php
/* This Echo statement will print out my message to the
the place in which I reside on.  In other words, the World. */
echo "Hello World!"; 
/* echo "My name is Humperdinkle!";
echo "No way! My name is Uber PHP Programmer!";
*/
?>

Результат:


Hello World!

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

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

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

← Операторы | Содержание | Include →

myblaze.ru

Стандарт комментирования кода в PHP / Habr

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

Практика


Итак, пример:

На первый взгляд смотрится не так уж красиво, но есть ряд преимуществ.
Главное преимущество — стандарт. Теперь о приятностях которые дают нам Zend и Eclipse:

В виде hint-подсказки среда разработки показывает нам развернутое описание функции,
где видно какого формата должны быть входные данные и что мы получим в итоге. «Но это еще не все ©»,
существуют системы автоматического создания документации,
и с их помощю можно получить полное описание нашего проекта,
основываясь только на описанных выше комментариях. Как это примерно выглядит:

эта страничка сгенерирована системой phpDocumetor встроенной в ZDE.

Синтаксис комментариев


Синтаксис для функции или метода
/**
* Имя или краткое описание (класса, метода, свойства, функции)
*
* Развернутое описание
* в несколько строк
*
* @имя_тега значение
* return тип_данных
*/

Синтаксис для свойства
/**
* Описание
*
* var тип_переменной
*/
И на последок список тегов с описанием:

  • @access [private | protected | public] (Контроль доступа для элемента)
  • @author Антонов А. <[email protected]> (Автор текущего элемента)
  • @param тип_данных $имя_переменной Описание (Описание для входного параметра)
  • return тип_данных Описание (Описывает тип возвращаемых данных функцией или методом)

Полный список на phpDocumentor Manual.

habr.com