Comments

Comments are code segments that PHP interpreter avoids executing. They are valuable to make notes inside your code so your program would be more understandable to you and anyone else. PHP supports two types of comments.

Single Line Comments

Single line comments are effective from the point they were started till the end of current line. A single line comment is started using two forward slashes (//).

$itemsPerPage = 50; // Number of items to be shown per page.

If you put the single line comment at the beginning of a line then whole line won’t be interpreted. For an example, in following case, $itemsPerPage won’t be defined.

//$itemsPerPage = 50;

This is a common tactic used in testing and debugging. That is without deleting original lines, commenting them out would help you to switch back when needed. If you wanted to see how pages would look like if items per page was 80, you can try out that as below.

//$itemsPerPage = 50;
$itemsPerPage = 80;

For single line comments, instead of two forward slashes, a hash sign (#) can be used. But using forwards slashes is common.

$itemsPerPage = 50; # Number of items to be shown per page.

Multi Line Comments

Multi line comments start with /* and ends with */. These can be used when you want to note down more information.

/*
 * Returns employee first name and last name as a string.
 * Empty string would be returned if a matching employee
 * doesn't exist.
 * $employeeId is the Employee ID number.
*/

function getEmployeeName($employeeId) {

}

Multi line comments are often used for introductions like above. In function introductions, it’s common to have spaces and asterix sign (*) in each line as above even though it’s not required. This format is followed for readability. Multi line comments can also be used when you want to comment out a whole part of the code (like trying a new function instead of an existing one).

phpDocumentor

phpDocumentor can automatically build well indexed HTML documentation once function (methods in OOP terminology) and class introductory comments are written to a given format. It can be a helpful tool when you work in large projects. Above example can be re-written according to phpDocumentor way as below.

/**
 * Returns employee first name and last name as a string.
 *
 * Empty string would be returned if a matching employee
 * doesn't exist.
 *
 * @param int $employeeId Employee ID number
 * @return string Employee first name and last name
*/

function getEmployeeName($employeeId) {

}