Как обозначаются комментарии на php
PHP поддерживает комментарии в стиле 'C', 'C++' и оболочки Unix (стиль Perl). Например:
Однострочные комментарии идут только до конца строки или текущего блока PHP-кода, в зависимости от того, что идёт перед ними. Это означает, что HTML-код после // . ?> или # . ?> БУДЕТ напечатан: ?> завершает режим PHP и возвращает режим HTML, а // или # не могут повлиять на это.
'C'-комментарии заканчиваются при первой же обнаруженной последовательности */ . Убедитесь, что вы не вкладываете друг в друга 'C'-комментарии. Очень легко допустить эту ошибку при комментировании большого блока кода.
User Contributed Notes 12 notes
Notes can come in all sorts of shapes and sizes. They vary, and their uses are completely up to the person writing the code. However, I try to keep things consistent in my code that way it’s easy for the next person to read. So something like this might help.
/* Title Here Notice the First Letters are Capitalized */
# Option 1
# Option 2
# Option 3
/*
* This is a detailed explanation
* of something that should require
* several paragraphs of information.
*/
// This is a single line quote.
?>
A nice way to toggle the commenting of blocks of code can be done by mixing the two comment styles:
<?php
//*
if ( $foo ) <
echo $bar ;
>
// */
sort ( $morecode );
?>
Now by taking out one / on the first line..
<?php
/*
if ($foo) <
echo $bar;
>
// */
sort ( $morecode );
?>
..the block is suddenly commented out.
This works because a /* .. */ overrides //. You can even «flip» two blocks, like this:
<?php
//*
if ( $foo ) <
echo $bar ;
>
/*/
if ($bar) <
echo $foo;
>
// */
?>
vs
<?php
/*
if ($foo) <
echo $bar;
>
/*/
if ( $bar ) <
echo $foo ;
>
// */
?>
It is worth mentioning that, HTML comments have no meaning in PHP parser. So,
WILL execute some_function() and echo result inside HTML comment.
As of php 8, single line comments starting exactly with «#[» have a special meaning: they are treated as «attributes», and they must respect the expected syntax. See: https://www.php.net/manual/en/language.attributes.php
So the following code throws an error in php 8+, while it is perfectly valid in php <8:
<?php
#[
my super cool comment
]
?>
To be safe, just always use «//» comments instead of «#». Maybe in the future there will be other special meanings for the «#» comments, who knows.
Comments in PHP can be used for several purposes, a very interesting one being that you can generate API documentation directly from them by using PHPDocumentor (http://www.phpdoc.org/).
Therefor one has to use a JavaDoc-like comment syntax (conforms to the DocBook DTD), example:
<?php
/**
* The second * here opens the DocBook commentblock, which could later on<br>
* in your development cycle save you a lot of time by preventing you having to rewrite<br>
* major documentation parts to generate some usable form of documentation.
*/
?>
Some basic html-like formatting is supported with this (ie <br> tags) to create something of a layout.
MSpreij (8-May-2005) says /* .. */ overrides //
Anonymous (26-Jan-2006) says // overrides /* .. */
Actually, both are correct. Once a comment is opened, *everything* is ignored until the end of the comment (or the end of the php block) is reached.
Thus, if a comment is opened with:
// then /* and */ are «overridden» until after end-of-line
/* then // is «overridden» until after */
Be careful when commenting out regular expressions.
E.g. the following causes a parser error.
I do prefer using # as regexp delimiter anyway so it won’t hurt me 😉
Comments do NOT take up processing power.
So, for all the people who argue that comments are undesired because they take up processing power now have no reason to comment 😉
// Control
echo microtime (), «<br />» ; // 0.25163600 1292450508
echo microtime (), «<br />» ; // 0.25186000 1292450508
// Test
echo microtime (), «<br />» ; // 0.25189700 1292450508
# TEST TEST TEST TEST TEST TEST TEST TEST TEST TEST TEST TEST TEST TEST TEST TEST TEST TEST TEST
# .. Above comment repeated 18809 times ..
echo microtime (), «<br />» ; // 0.25192100 1292450508
?>
They take up about the same amount of time (about meaning on a repeated testing, sometimes the difference between the control and the test was negative and sometimes positive).
it’s perhaps not obvious to some, but the following code will cause a parse error! the ?> in //?> is not treated as commented text, this is a result of having to handle code on one line such as <?php echo ‘something’ ; //comment ?>
<?php
if( 1 == 1 )
<
// ?>
>
?>
i discovered this «anomally» when i commented out a line of code containing a regex which itself contained ?>, with the // style comment.
e.g. //preg_match(‘/^(?>c|b)at$/’, ‘cat’, $matches);
will cause an error while commented! using /**/ style comments provides a solution. i don’t know about # style comments, i don’t ever personally use them.
a trick I have used in all languages to temporarily block out large sections (usually for test/debug/new-feature purposes), is to set (or define) a var at the top, and use that to conditionally comment the blocks; an added benefit over if(0) (samuli’s comment from nov’05) is that u can have several versions or tests running at once, and u dont require cleanup later if u want to keep the blocks in: just reset the var.
personally, I use this more to conditionally include code for new feature testing, than to block it out. but hey, to each their own 🙂
this is also the only safe way I know of to easily nest comments in any language, and great for multi-file use, if the conditional variables are placed in an include 🙂
for example, placed at top of file:
<?php $ver3 = TRUE ;
$debug2 = FALSE ;
?>
and then deeper inside the file:
<?php if ( $ver3 ) <
print( «This code is included since we are testing version 3» );
>
?>
<?php if ( $debug2 ) <
print( «This code is ‘commented’ out» );
>
?>
In php there are 3 types of comments
1.single line c++ style comment(//)
2.single line Unix shell stype comment(#)
3.multi line c style comment(/*/)
single or multi line comment comes to the end of the line or come first to the current block of php code.
HTML code will be printed after //. > or #. >
closing tag breaks the php mode and return to html mode.
different comments in different tags:
===================================
<H1>Standard tag: <?php //echo » standard tag»; ?> single line c++ style comment</H1>
<p>The header above will break php mode and return html mode and show ‘Standard tag:single line c++ style comment'</p>
<H1>Standard tag: <?php # echo » standard tag»; ?> single line unix shell style comment</H1>
<p>The header above will break php mode and return html mode and show ‘Standard tag:single line unix shell style comment'</p>
<H1>Standard tag: <?php /*echo » standard tag»; */ ?> multi line c style comment</H1>
<p>The header above will break php mode and return html mode and show ‘Standard tag:multi line c style comment'</p>
<H1>short echo tag: <?= // » short echo tag»; ?> single line c++ style comment</H1>
<p>The header above will break php mode show a unexpected syntex error'</p>
<H1>short echo tag: <?= # » short echo tag»; ?> single line c++ style comment</H1>
<p>The header above will break php mode show a unexpected syntex error'</p>
<H1>short echo tag: <?= /*echo » short echo tag»*/ ; ?> multiple line c style comment</H1>
<p>The header above will break php mode show a unexpected syntex error'</p>
<H1>Short tag: <? //echo » short tag»;?>single line c++ style comment</H1>
<p>The header above will break php mode and return html mode and show ‘Short tag:single line c++ style comment'</p>
<H1>Short tag: <? #echo » short tag»;?>single line unix shell style comment</H1>
<p>The header above will break php mode and return html mode and show ‘Short tag:single line unix shell style comment'</p>
<H1>Short tag: <? /* echo » short tag»;*/?>multi line c style comment</H1>
<p>The header above will break php mode and return html mode and show ‘Short tag:multi line c style comment'</p>
<H1>Script tag: <script language=»php»> // echo » script tag»;</script>single line c++ style comment</H1>
<p>The header above will break php mode and return html mode and show ‘Script tag:single line c++ style comment'</p>
<H1>Script tag: <script language=»php»> /* echo » script tag»;*/</script>multi line c style comment</H1>
<p>The header above will break php mode and return html mode and show ‘Script tag:multi line c style comment'</p>
<H1>Script tag: <script language=»php»> # echo » script tag»;</script>single line unix shell style comment</H1>
<p>The header above will not break php mode </p>
PHP Комментарии
Комментарий в коде PHP — это строка, которая не выполняется как часть программы. Его единственная цель — быть прочитанным кем-то, кто просматривает код.
Комментарии могут быть использованы для:
- Чтобы другие поняли ваш код
- Напоминания себе о том, что вы сделали. Большинство программистов через год или два вернулись к своей собственной работе, и им пришлось заново выяснять, что они сделали когда-то. Комментарии могут напомнить вам, о чём вы думали, когда писали код
PHP поддерживает несколько способов комментирования:
Пример
Синтаксис однострочных комментариев:
<?php
// Это однострочный комментарий
# Это также однострочный комментарий
?>
Пример
Синтаксис для многострочных комментариев:
<?php
/*
Это многострочный блок комментариев, охватывающий несколько строк.
*/
?>
Пример
Использование комментариев, чтобы пропустить части кода:
<?php
// Вы также можете использовать комментарии, чтобы пропустить части строки кода
$x = 5 /* + 15 */ + 5;
echo $x;
?>
ПАЛИТРА ЦВЕТОВ
ПРИСОЕДИНЯЙТЕСЬ!
Получите ваш
Сертификат сегодня!
Связь с админом
Если вы хотите сообщить об ошибке, а также внести предложение о работе сайта, добавить объявление или рекламу на сайт, не стесняйтесь отправить админу электронное письмо на email:
Топ Учебники
Топ Справочники
Топ Примеры
Веб Сертификаты
Этот сайт оптимизирован для обучения и тестирования. Примеры могут быть упрощены для улучшения чтения и базового понимания. Учебные пособия, ссылки и примеры постоянно пересматриваются, чтобы избежать ошибок, но мы не можем гарантировать полную правильность и работоспособность всего контента. Используя этот сайт, вы соглашаетесь с тем, что прочитали и приняли условия использования, cookie и политику конфиденциальности.
Также вы можете абсолютно бесплатно скачать офлайн версию сайта W3Schools на русском архивом с GitHub и пользоваться локально на своём компьютере.
Также доступна версия сайта W3Schools на украинском языке.
Copyright 1999-2021 by Refsnes Data. All Rights Reserved.
Сайт работает на фреймворке W3.CSS.
PHP Code Style Conventions
В данной статье рассматривается подход к написанию и оформлению PHP кода. Нижеизложенные моменты были сформированы путем анализа существующих подходов компаний и личного опыта.
Правила именования файлов и папок
Все названия для папок и файлов должны быть осмысленными и говорящими (не требующие дополнительного разъяснения).
Папки
Все папки именуются в нижнем регистре с разделением слов с использованием символа — (минус).
Если папка хранит в себе классы, которые относятся к пространству имен (namespace), то папка именуется в соответствии с названием пространства имен (namespace).
Разрешенные символы для именования папок: латинские буквы и символ — (минус).
Файлы
Все файлы, относящиеся к проекту, именуются в нижнем регистре с разделением слов с использованием символа — (минус).
Если файл является файлом класса, то именуется в соответствии с названием класса.
Правила именования пространств имен, классов, методов и переменных
Все названия должны быть осмысленными и говорящими (не требующие дополнительного разъяснения).
Пространства имен
Названия пространств имен должны быть в нижнем регистре и состоять из одного слова. В случае необходимости именовать пространств имен более одного слова производится дробление на составные части, являющиеся вложенными пространствами имен.
Классы
Названия классов должны соответствовать PascalCase . В PascalCase каждое слово начинается с заглавной буквы.
Трейты имеют постфикс Trait . Интерфейсы имеют постфикс Interface . Абстрактные классы имеют префикс Abstract .
Методы
Названия методов должны соответствовать camelCase . camelCase должен начинаться со строчной буквы, а первая буква каждого последующего слова должна быть заглавной. Все слова при этом пишутся слитно между собой
К названиям методов применяются следующие правила:
- Название метода должно передавать намерения программиста
- Название метода должно сообщить, почему этот метод существует, что он
делает и как используется ( isPostRequest , getRequestType , parseSchemaElement , renderPageWithSetupsAndTeardowns ) - Название метода не должно быть коротким
- Название метода должно начинаться с глагола
- Названия boolean методов должны содержать глагол is , has или can
Переменные
Названия переменных должны соответствовать camelCase . camelCase должен начинаться со строчной буквы, а первая буква каждого последующего слова должна быть заглавной. Все слова при этом пишутся слитно между собой
Константы должны быть соответствовать UPPER_CASE_SNAKE_CASE . В UPPER_CASE_SNAKE_CASE все слова пишутся заглавными буквами, а пробелы заменяются знаками подчеркивания.
К названиям переменных применяются следующие правила:
Название переменной должно передавать намерения программиста
Название переменной должно сообщить, почему эта переменная существует, что она делает и как используется
Название переменной не должно быть коротким
В названии переменной не должен использоваться тип данных. Исключение составляет Map ( $typesMap , $statesMap ), т.к. в ином случае его не отличить от массива с данными.
Если переменная хранит признак, то он должен быть включен в название ( unpaidProject )
Переменные, отражающие свойства объекта, должны включать название объекта ( userIsAdmin , messageIsSend , figureCanBePainted , projectName )
Переменные и свойства объекта должны являться существительными и называться так, чтобы они правильно читались при использовании, а не при инициализации
Плохо:
Хорошо:
Названия boolean переменных должны содержать глагол is , has или can
Запрещены отрицательные логические названия
Плохо:
Хорошо:
При наличии свойств (пункт 8 и аналогичные), порядок имя переменной состоит из: имени объекта, по отношению к которому используется переменная), свойство и продолжение названия переменной ( userHasRoleAdmin , statusIsActive )
Правила оформления кода
В первую очередь ставится пространство имен (namespace), которое используется (если есть). Далее пишется конструкции использования классов ( use ). В случае использования нескольких
классов одного пространства имен происходит группировка с помощью конструкции <. >. Далее идет объявление класса.
Фигурные скобки ставятся на той же строке и разделяются пробелом.
- Внутри не разделяются пробелом.
- Снаружи разделяются пробелами управляющие конструкции
- После названия метода/функции — пробел не ставится.
Каждая переменная должна быть объявлена на новой строке.
Условия и служебные вызовы методов разделяются переносом строки, переменные и работа с ними переносами строк не разделяются.
Внутри условий и циклов дополнительный перенос на новую строку не ставится.
Содержимое класса разделяется сверху одной пустой строкой.
Перед возвращаемым значением( return ) обязательно ставится перенос строки, если метод не состоит из единственной строки.
Если условие является большим, то обязательно выделить его в одно или несколько смысловых выражений и использовать его (их) в условии.
Плохо:
Хорошо:
Комментирование кода
В общем случае комментарии запрещены (НЕ "всегда"). Любой участок кода, который необходимо выделить или прокомментировать, надо выносить в отдельный метод.
Комментарии должны быть расположены перед объявлением классов, переменных и методов и быть оформлены в соответствии с PHPDoc. Комментарий перед классом должен содержать описание бизнес-логики и отражать его назначение с приведением примеров использования.
Однострочный комментарии обозначаются символами // , а многострочный /*. */ .
Готовые алгоритмы, взятые из внешнего источника, должны быть помечены ссылкой на источник.
Правила написания кода
Везде, где имеет смысл, должнно быть прописано declare(strict_types=1);
В функциях/методах вместо отсутствующего скалярного значения используется null . 0 и пустую строку нельзя использовать в качестве показателя отсутствия значения.
Нельзя изменять переменные, которые передаются в метод на вход (исключение — если эта переменная объект).
Нельзя нескольким переменным присваивать одно и то же значение. Для проверки наличия ключа в ассоциативном массиве используется array_key_exists , а не isset . Нельзя смешивать в массиве строковые и числовые ключи. Нельзя сортировать ассоциативные массивы.
Строки обрамляются одинарными кавычками. Двойные кавычки используются только, если:
- Внутри строки должны быть одинарные кавычки
- Внутри строки используется подстановка переменных
- Внутри строки используются спец. символы \n , \r , \t и т.д.
Вместо лишней конкатенации используем подстановку переменных в двойных кавычках
В методах должна быть использована максимально возможная типизация, включая тип возвращаемого значения( : type ). Все параметры и их типы должны быть описаны в объявлении метода либо в PHPDoc. Методы названия, которых начинаются c check и validate , должны выбрасывать исключения и не возвращать значения.
Все методы класса по умолчанию должны быть private . Если метод используется наследниками класса, то он объявляется protected . Если используется сторонними классами, тогда public .
Если метод может вернуть null , то желательно реализовать шаблон проектирования Null object, или выбросить исключение, или вернуть объект особого случая (пример: пустой массив).
При возврате из метода данных типа json — недопустимо писать return true , всегда использовать конструкцию return [‘success’ => [‘message’ => ‘. ‘]] или [‘error’ => [‘message’ => ‘. ‘]] . message приведен для примера, можно использовать любые ключи в неограниченном количестве.
Метод должен явно отличать нормальные ситуации от исключительных.
По умолчанию тексты исключений не должны показываться пользователю. Они предназначены для логирования и отладки. Текст исключения можно показать пользователю, если оно явно для этого предназначено.
В условном операторе должно проверяться исключительно boolean значение. В сравнении не boolean переменных используется строгое сравнение с приведением типа ( === ), автоматическое приведение и нестрогое сравнение не используются.
При использовании в условном выражении одновременно операторов И и ИЛИ обязательно выделять приоритет скобками.
What are comments in PHP and why do we must use them ?
Everybody knows about comments because it is the first thing which is taught in schools and colleges. We were told that commented code is never executed in a program, it is correct but not completely, I will show you in details in this post but let us go through its definition first.
What are comments in PHP ?
Comments, be in PHP or any other programming language is the text in source code which is not executed when a program is compiled, interpreted or run, that is, the text we write in comments are not visible to end users. Moreover, comments are useful to share an idea or working of a code block in a team of developers working on the same project.
Code block can be anything, a single line of code, or a function or a class or the file itself. They are even important for solo developers since comments can remind the idea or algorithm a developer applied a long back ago. Since this post is regarding PHP then I am supposed to give you more details on PHP comments.
Types of comments in PHP
PHP supports ‘C’, ‘C++’ and Unix shell-style (Perl style) comments. As per the PHP standards, there are three (3) ways to comment out code.
In line / Single line comments
In line or single line comments are denoted as // (double forward slashes). The single line after // becomes the text for comment. For example.
echo “Hello World”; //This is single line comment
Keyboard short-cut for one line comment
In phpstorm IDE, select the line or put cursor on the line you want to comment and press Ctrl+/
Multi-line comments
Multi-line comments are used when we want to comment out a whole block of lines of code. The comment text is enclosed in /* and */. For example
/*echo “This is the first line of code”;
echo “This is the second line of code”*/
Keyboard short-cut for multi line comment
In phpstorm IDE, select the lines from start to till you want to comment and press Ctrl+shift+/
Documentation comments / DocBlock
This is a different kind of PHP comments that has its own standard — it is called DocBlock. DocBlocks are blocks of texts which are used to generate documentation using phpDocumentor also known as phpDoc. Interestingly, they are more important and we must use them if we are developing a complex software product, everything must be documented in that case.
DocBlocks are modified version of Multi line comments and can be easily identified by their distinct style. For example.
<?php
/**
* This comment will be added as text
* for DummyClass in documentation
*/
Class DummyClass <
/**
* This comment will be added as text
* for DummyFunction in documentation
*/
Public function dummyFunction()
<
//This comment will not be added in documentation
As you can see, DocBlock comments start with /** and ends with */
Keyboard short-cut for DocBlock
In phpstorm IDE, put the cursor above the class or function name, type /** and press enter, it will automatically generate DocBlock with some additional field which you can remove for the time being because we will see PHP documentation in another article.
Apart from standard types of comments in php, I also use one different type of comment which is ToDo comment.
todo comments
todo comments are nothing but single line comments but after // we add todo. For example
//todo This part I will see after coming from vacation
In phpsorm, press Ctrl + E and select TODO, you will see all the todos which needs your attention.
Conclusion
So friends, we now came to the end of this post where we seen different kinds of comments in PHP and their usage in our code and documentation. Which type did you find most useful, tell me in the comments below.