Development Tools Using PHP with MySQL Filtering Input for Queries Using a WHERE Clause

Robert Mews
Robert Mews
11,540 Points

PHP Comments

More of a question about best practices when it comes to PHP comments. Randy commented his PHP like this:

/*
 * Retruns an array of product information for the product that matches the sku
 * Returns a boolean false if no product matches the sku
 * @param   int     sku     the sku
 * @return  mixed   array   list of product information for the one matching product
 *                  bool    false if no product matches
*/

I also see these types of comments on GitHub with the @param and @return. Curious on if this is typical and best practice?

1 Answer

Codin - Codesmite
Codin - Codesmite
8,593 Points

@param and @return are PHP documention tags. If you are using tools such as PHPdocumentor it will allow you to scan for tags such as @param to easily document your code.

You probably see it used a lot on Github because they are open source projects and make it a lot easier for other developers to read and modify your code.

In most proffesional workplaces the same is done in commenting if you are coding part of a project that other developers may need to reference or edit at a later time it makes it easier for them to understand how your code works and what everything references through comment documentation.

It is not always the same depending on the workplace but you will find looking at projects on Github most of the opensource community use PHP documentation tags.

Here is a link to PHPdocumentator for more information and a better idea why it is used: http://phpdoc.org/