PHP Comments5:16 with Alena Holligan
Comments can help you clearly define what and program needs to do. And the most helpful comments, let others, and your future self, know what your code is supposed to do and WHY. We'll take a look at several different ways to write comments in PHP.
Single Line Comments
Single line comments can also be written using #
# this is a comment line // this is a comment line /* this is a comment line */
A DocBlock is always associated with one, and just one, Structural Element in PHP; so this may either be a file, class, interface, trait, function, constant, method, property or variable. Using a DocBlock you are able to effectively document your application, by describing the function of, and relations between, elements in your source code.
In reality a DocBlock is in fact the name for a combination of a, so-called, DocComment and a block of the PHPDoc Domain Specific Language (DSL). A DocComment is the container that contains documentation that can be formatted according to the PHPDoc Standard.
Commonly a piece of PHPDoc consists of the following three parts in order of appearance:
Summary A short piece of text, usually one line, providing the basic function of the associated element.
Description An optional longer piece of text providing more details on the associated element’s function. This is very useful when working with a complex element.
A series of tags These provide additional information in a structured manner. With these tags you can link to other elements, provide type information for properties and arguments, and more.
/** * A summary of this PHP Basics course on Treehouse. * * A *description*, that can span multiple lines, to go _in-depth_ into the details of this * element and to provide some background information or textual references. * * @source Alena Holligan, PHP Teacher at Treehouse * * @param string $myArgument With a *description* of this argument, these may also * span multiple lines. * * @return type (a PHP Programmer ;) ) */
You need to sign up for Treehouse in order to download course files.Sign up