PHP Comments
In this lesson we will discuss comments and at the end of the lesson you will understand what they are, why you should use them and how to correctly insert then into your code.
What are comments
Comments are an important part of any programming language and every programming language supports them, even markup languages like HTML. Comments are written or inserted within code but the are not executed in the way your code might be, they are essentially ignored when your code is run.
Why use comments
Comments are an excellent way of making notes within your code. If created properly, they will have no impact on the functionality of your code. Most programmers use comments to explain what a block of code does, or how it relates to other code.
Think about when you are writing a piece of code. You are likely to be very familiar with what that code should do, and how it might impact other code that may exist elsewhere. Now imagine it is several weeks later and you have moved onto other projects, will you accurately remember what that code does at first glance? Probably not, you will have to read it and read to other code that it refers to in order to work out what it is supposed to do.
It’s a bit like a street map without any labels, just a series of intersecting lines that made complete sense when you drew the map. By adding labels you are reminded of what the streets are called, and coding comments work in the same way. They provide guides for you and others that may be reading your code long after you have written it.
Comments can contain anything that you think may be useful to you or other developers. Instructions and explanations are common uses. Creation and editing dates are another use, as are author or team names. Since comments are essentially ignored by a browser, comments can also be used to “comment out” or hide code that you do not want to be executed. This is often used when a developer is experimenting or debugging.
Comments will take time to create but you will be writing better code for you and for others that will read your code later.
How to insert comments
PHP has a number of different ways that enable you to insert comments into your code. All PHP comments must be located within PHP tags (<?php ?>). Although they are not processed as PHP code, they are still part of the PHP language and if you locate your comments outside PHP tags they will be treated as HTML by the server.
Single line comments
If you want to have a single line comment you can use two forward slashes followed by the text that you want included in your comment. Be sure that this comment is contained on one single line.
echo "This is a string,"; // This is a comment echo " and this is another string.";
In this example there is a comment in between two echo commands. The strings that the echo commands are outputting are two parts of one sentence. Try this and observe the result in a browser.
You will see that the browser ignored the comment and only executed the two echo commands. The result is a single string, as we would have expected (the two echo commands would output their strings one after the other without any other instructions like a <br> tag that would create a line break for example). So we can see that the comments were ignored by the browser!
Do you get the same result?
If not, revise your code and be sure that to the left of your comment text you are using two forward slashes without any spaces between them and that you comment is on a single line.
Let’s take a closer look at what the browser actually sees. If you view the source code from within your browser (right click and choose “view source”) you will see exactly what the server sent to your client. Look very carefully and you will see that the comments that you know are in the PHP code are nowhere to be seen. Why is this?
Remember that the server will take all of your PHP code and execute it but it will always return pure HTML to the browser? Well your comments are also PHP code, and as such they are removed by the server before the web page is sent to the client.
And that is is for single line comments. There is one other way of inserting single line comments into your PHP and the is using a hash or pound sign:
echo "This is a string,"; # This is also a comment echo " and this is another string.";
This method is not considered standard and we would encourage you to use double forward slashes to create all of your comments.
Multi-line comments
The double forward slash technique is great for single line comments and if you wanted more that one line of comments you could use a double forward slash for each line:
echo "This is a string,"; // This is a comment, // and this is more of this comment, // and one more line wraps up this comment. echo " and this is another string.";
Try that and see if it works.
Hopefully you saw that yes, it works, but there is a better way. We can enclose multiple lines within a comment by using a single forward slash followed by an asterisk (/*) at the beginning if the comment block and the reverse, an asterisk followed by a forward slash (*/) at the end of the comment block:
echo "This is a string,"; /* This is a comment, and this is more of this comment, and one more line wraps up this comment. */ echo " and this is another string.";
Try this for yourself. You’ll see that you can have as many lines of code within the opening and closing comment markers as you want. An easy way to remember the order of the forward slash and asterisk is that the asterisk is always closer to the content of the comment.
The opening and closing comment markers are strictly observed by the PHP processor. As soon as the processor sees a close comment marker it will switch from comment mode back to normal code execution mode. This becomes a problem if you accidentally next comments within comments – avoid this! Each of your comments should be a single block with a clear start and finish.
And that’s all we need to know about multi-line comments.
It may be hard to see now but comments are a great investment in the value of your code. Once you have been coding for some time and you have to revisit code that wrote many months ago you may have no idea what it does and you’re probably going to spend a lot of time working it out. But with some well placed and articulate comments you should find exactly what you need to know quickly.
Spend some time experimenting with single and multi-line comments to get more acquainted with them before you move on.
Now that we are comfortable creating a variety of PHP comments, in the next lesson we explore the world of variables.