This course will be retired on June 1, 2025.

Heads up! To view this whole video, sign in with your Courses account or enroll in your free 7-day trial. Sign In Enroll

PHP Basics

Preview

Start a free Courses trial
to watch this video

Sign up for Treehouse

PHP Comments

5: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.

Workshop: Basic Error Handling 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 */

DocBlock Formatting

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.

Example:

/**
  * 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 ;) )
  */

Further Reading

Related Discussions

Have questions about this video? Start a discussion with the community and Treehouse staff.

Sign up

    Related Discussions

    Have questions about this video? Start a discussion with the community and Treehouse staff.

    Sign up

    Code can be challenging to read no matter how it's written. 0:00
    Comments let you leave notes in your code. 0:04
    Comments are ignored by the server but they're useful for 0:07
    letting other humans know what your code does, how it does it, and 0:10
    why you wrote the program the way you did. 0:15
    Not only is it good to document what is happening, 0:17
    it can also be helpful to document why. 0:20
    There could be a specific business need that causes you to write something 0:23
    in a particular way. 0:27
    For instance, if we think about this course in terms of an application, 0:29
    a user will come to this course having a basic knowledge of HTML. 0:34
    We are going to assume they have no prior programming skills. 0:38
    And we want them to have a solid project to take away, so 0:42
    that they have some practical skills to practice. 0:45
    You don't want someone, including yourself, 0:48
    to be making a change later without considering the business need. 0:51
    This course could be designed completely differently if we assume that the person 0:55
    learning php has experience in another programming language. 0:59
    Comments help us to get organized and stay organized. 1:04
    There are three types of comments in PHP, single line, 1:07
    multi-line, and what's called doc block comments. 1:11
    Let's take a look at how to add comments in your PHP programs. 1:15
    The first type of comment is a single line comment 1:20
    which you create by typing two forward slashes. 1:23
    You can find a forward slash on the question mark key. 1:27
    We can use a single line comment to add a brief note such as our first PHP script. 1:30
    You can also add comments after a statement but on the same line. 1:37
    Anything after the double slashes will be ignored when the script is processed. 1:44
    Because comments are ignored when php processes a program, 1:48
    we can also use them to temporarily prevent a line of code from running. 1:51
    We call this commenting out a line of code. 1:56
    Let's duplicate this line and then change it to say hello treehouse. 1:59
    Well then comment out our Hello World. 2:06
    We do this by adding the double slashes to the beginning of the line. 2:11
    Then we can run the script in our console again. 2:16
    As you can see, it only outputs Hello Treehouse, not Hello World and 2:21
    none of the comments appear. 2:26
    If we go back and remove the double slashes from the Hello World line. 2:28
    And add them to the Hello Treehouse line, we can run our script again. 2:33
    And this time we see Hello World. 2:40
    There will often be times when you need to add a longer comment. 2:43
    For example, you may want to explain why you chose to write your code 2:46
    in a certain way, or you might want to add multiple lines to make your comments 2:50
    easier to read, just like you do when writing paragraphs or bullet points. 2:54
    You can make a single line comment as long as you want, 3:00
    even wrapping to a new line, 3:09
    as long as you don't add a hard return. 3:15
    Another option is to have multiple lines that all start 3:21
    with a // This is a second comment line. 3:26
    But there is an easier way to add comments that span multiple lines, 3:29
    like we do with HTML tags there's an opening and 3:34
    closing sequence we can use for adding multiple line comments in php. 3:37
    We start with a single forward slash and then add an asterisk. 3:42
    Then we close the comment block in the opposite way, 3:48
    the asterisk followed by a single forward slash. 3:52
    We can then add as many line comments as we want between these tags. 3:56
    The third type of comment is called a doc block which programmers use to give 4:01
    specific documentation about an entire file or a section of code. 4:05
    This documentation should include things such as a summary, author, version, 4:10
    and license. 4:15
    You can learn about specific uses for the doc blocks in the teacher's notes. 4:17
    Let's add a simple doc block to the top of our file. 4:21
    A doc block is much the same as a multiline comment. 4:23
    It starts and ends the same way. 4:28
    The only difference is that each line also starts with a space, asterisk, space. 4:33
    This file is our first "Hello World!" script. 4:41
    @author: Alena Holligan. 4:53
    Make sure you put your name as the author and give yourself credit. 4:56
    Great job writing your first program. 5:01
    There are many more fun and exciting things just around the corner. 5:02
    Give your brain a little chance to digest what you learned so far, but 5:07
    don't wait too long to jump back into the unit converter we'll 5:11
    be writing in the next section. 5:14

    You need to sign up for Treehouse in order to download course files.

    Sign up

      You need to sign up for Treehouse in order to set up Workspace

      Sign up