Welcome to the Treehouse Community

The Treehouse Community is a meeting place for developers, designers, and programmers of all backgrounds and skill levels to get support. Collaborate here on code errors or bugs that you need feedback on, or asking for an extra set of eyes on your latest project. Join thousands of Treehouse students and alumni in the community today. (Note: Only Treehouse students can comment or ask questions, but non-students are welcome to browse our conversations.)

Looking to learn something new?

Treehouse offers a seven day free trial for new students. Get access to thousands of hours of content and a supportive community. Start your free trial today.

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,598 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/