We've been using single line comments up until now to help explain what's happening within our code snippets. It's time to take a look at the other types of comments available to us, so that we have better methods of learning for when our snippets become a little more complicated.
Single Line
Single line comments are the ones that we've been using so far. They begin with a double // slash, and can occupy a single line. Like this.
<?php
// This is a single line comment.
Whitespace doesn't effect them; they begin at the double forward slash, and terminate at the end of the line. This means that we could place them after our code if we prefer. Here's an example.
<?php
$panda = 'Awesome'; // Set panda to awesome.
This works just fine. However, I prefer to place my comments on the line above my code. This makes the line much shorter and easier to read. Within the examples in this book, I'll be placing my comments on the line above the code that they are describing. You're welcome to do the same, or to choose your own position.
If we want for our comment to span multiple lines, we can quite happily provide more single line comments, like this.
<?php
// Pandas are awesome.
// It's because they are kind of like cats.
// Except more fluffy, and they kind of look like
// how cats look in anime.
There's a much better way though.
T> It's worth noting that a hash # character can also be used in the place of a double slash to begin a comment. However, the double slash is preferred, and the hash comments are simply a relic of a bygone era!
Multi-Line
If we want for a comment to span multiple lines, we can use the multi-line syntax instead. Let's take a closer look, shall we?
<?php
/* Pandas are awesome.
It's because they are kind of like cats.
Except more fluffy, and they kind of look like
how cats look in anime.
*/
$pandas = 'Awesome!';
Everything between the /* and the */ will count as a comment. Even if it spans multiple lines. The comment looks a little unbalanced though, so what many developers like to do is use additional stars on each line for alignment. Here's an example.
<?php
/* Pandas are awesome.
* It's because they are kind of like cats.
* Except more fluffy, and they kind of look like
* how cats look in anime.
*/
$pandas = 'Awesome!';
As you can see, all of the star * characters of the comment are in alignment, and the comment looks much, much neater.
These types of comments can be really useful using a process known as 'commenting out code' to aid the debugging process. Here's an example.
<?php
// Set a string.
$pandas = 'awesome!';
// Set a string.
$pandas = 'fantastic!';
// Output.
echo 'Pandas are ' . $pandas;
We know that this piece of code will output Pandas are fantastic!. Let's imagine that we want to try and see how it looks if pandas are awesome, instead. We might want to go back to them being fantastic for later, so this test is only temporary. Let's comment out the middle bit.
<?php
// Set a string.
$pandas = 'awesome!';
/*
// Set a string.
$pandas = 'fantastic!';
*/
// Output.
echo 'Pandas are ' . $pandas;
There, we've used the multi-line comment symbols to skip the middle statement so that PHP ignores the code and pandas are awesome again. If we'd like them to be fantastic once more, we simply remove the symbols.
There's one final form of comment that we need to take a look at. It's a little advanced, but I think you can take it! You're a smart, beautiful AND / OR handsome reader, after all.
Doc Blocks
Doc blocks are a special type of comment. Other programs known as documentation generators can read these special types of comments, and use the information provided within to generate documentation for your project.
Doc blocks look similar to multi-line comments, except that the opening tag uses two stars instead of one. Here's an example.
<?php
/**
* Description of pandas.
*/
$pandas = 'awesome!';
When our automated documentation system runs, our $pandas variable will have a description of what it does. If we want to, we can provide additional information that might be useful to our documenter. Let's have another example, shall we?
<?php
/**
* Description of pandas.
*
* @var string
*/
$pandas = 'awesome!';
We can provide extra metadata to our doc blocks using properties that are prefixed with an @ symbol. Parameters associated with these properties are placed on the same line, and multiple parameters can be separated with spaces.
With the provided @var property, our documentation system knows that the $panda variable contains a string value, and can display this information to help others learn more about the code.
Don't worry too much about these doc blocks, we'll stick to the other comments for now. In a later chapter I'll start to introduce them. I just wanted you to be aware of them, just in case you happen to see them somewhere else.
In the next chapter, we'll be taking a look at forks, so you better go and raid your cutlery drawer!
My books are available online for free to encourage learning. However, if you'd like for me to keep writing, then please consider buying a digital copy over at Leanpub.com.
It's available in PDF, ePub, and Kindle format, and contains a bunch of extras that you won't find on the site. I have a full-time job, and I write my books in my spare time. Please consider buying a copy so that I can continue to write new books from the comfort of my sofa!