3.3 Comments in PHP

Hello, and welcome back to this Tuts+ course on PHP for WordPress. In this part of the course, I'm gonna show you something that is quite straightforward but much too often left out of WordPress PHP code, and that's commenting. Now, commenting is something that you might think, I don't have the time for that. I'm too busy writing my code, and writing functions and all the rest of it, which we'll learn about on this course. But before you start, I think it's a really good idea to learn best practices for adding comments to a code. There are three reasons for this. The first one is because, in some cases, comments are essential in order to tell WordPress exactly what a file is for, and I'll show you an example of that with a custom page template. The second reason is for your own benefit. If you write some PHP code and you create a file, say in your theme or for a plugin, and then you don't touch that code for quite a while, sometimes you could come back to a file years later, you might have some code that you need to debug. If you don't know what that code does, it's much harder to debug it. Now you might be thinking to yourself, of course I know what that code does, cuz I wrote it in the first place. But the reality is that months or years later, you might not remember exactly what that code does. And in particular, you might not remember how it interacts with other code on your site. So for example, you might have a hook which pulls in a function from somewhere else in your theme, and you don't know what that's pulling in or what it's doing. And you might have a function where it's not entirely clear what it's doing. So adding detailed comments for yourself can make your life much easier when it comes to editing or debugging your code. The third reason is that if you're working with other people on code, which would either be if you're working as part of a team. Or alternatively if you want to write code that will be released to the public, either via the WordPress theme or plugin directories or by selling it direct to users, it's really important that your code is well-commented. And in fact, if you submit a theme or a plugin that doesn't have good comments, there's a very good chance that it'll get rejected. And that's because users of your code might want to debug it themselves in the future. They might want to fork it, which means they make a copy of it and then edit that to create their own version of the code. Or they might want to, for example, create a child theme of your theme, which they then use as a parent theme. Or they might want to create a plugin that hooks into some code in your theme. Now if you can add comments in your code, they'll understand exactly what's going on and how they can either edit or make best use of that code. So hopefully I've convinced you that using PHP commenting is a good idea. And here on the codex you'll see some guidance of how to use it in WordPress. And that'll include general PHP commenting, and what syntax to use. And it will also include the specific comments that you need to use for template files to tell WordPress what they're doing. And here, on the PHP site, you can see a bit more about what kind of comments work and what kind of comments don't in PHP, more generally outside WordPress. So let's work through some examples of different ways to add comments in WordPress. Here I've got a blank file. This isn't actually a plugin file or a theme file. It's just a file I'm gonna use to demonstrate some commenting techniques that you can access with the notes for this course. So let's start with a multiline comment. So the first thing I need to do is open up PHP for this file. Although this is a PHP file, you do always have to type PHP at the beginning. Now I want to add a comment here that will either go on a line all on its own or it'll span multiple lines or it'll really stand out. And to do this, I use multiple line comments. And I'll show you shortly how those are different from single line comments. So there's one basic way that you add a multiline comment. Now if I wanted to, I could add, As much as I want it here. What gives me is the option to add as much text as I want in my comments. Now I tend to use this in my theme and functions file when I want to make a piece of code really obvious when I'm scanning down the page. And let me show you a functions file from one of my themes. So you can see here, although this is only one line, I'm using a multiline comment to make it really obvious what I'm doing here. And in order to make it even more apparent, instead of just using one asterisk, which is all you need to do to get it to work, I'm actually using multiple asterisks. So here I'm typing a whole line full of asterisks. And then here you have to make sure it's before the slash. So your multiline comment will open with a slash and an asterisk. And then it will close with an asterisk and then a slash. Now, because you've used that slash and asterisk, you don't actually have to use asterisks here. What you could do instead is something like that. And that just demarcates your code as somebody scans down the document. And you can see that that works perfectly well, because these dashes here are actually just included in this multiline comment that's demarcated by the opening slash and asterisk. I'm gonna take it back to those asterisks. So it's up to you which one of those you chose to use. You could either just use a slash and an asterisk, or you could add multiple asterisks or dashes or whatever you want to make it really obvious that you've got a comment here. And that will break up your code and make it easy for you to find things in the future. So for sake of completeness, You can just use one asterisk. So that's a multiline comment. Now one of the great things about these is that you can add punctuation within them. So here you can see I've added dashes, hyphens, in order to substitute for bullet points. So this gives me plenty of information on exactly what this file is, and what it's doing, and how I can override it if I want to. Now these comments here don't tell WordPress anything. WordPress skips these and will go straight to if have_posts, because this is just an include file, it's actually the loop file, for a page in my theme. In some cases, you'll find that having comments at the beginning of a file is actually essential in order for WordPress to work with that file. So here you can see I've got a custom page template. And a custom page template is something that you use to give users of your theme multiple options for displaying pages. So instead of just having a template called page.php, you would have multiple templates and you can select them from a drop-down menu on the page editing screen. And you can see here I've included information as to what this does. And that at the beginning of the file, as long as you include this line here, Template Name, colon, Full width page, that will tell WordPress that this is a custom page template. So let me add that to my demo file. So I'll then close my comment. And that's how you tell WordPress that you've got a custom page template in your theme. Now that's not the only place that you need to use specific comments, another one is with plugins. So here are the opening lines of the Akismet plugin that comes loaded with every new version of WordPress. And you can see there are some lines here that tells WordPress what the plugin does. So going back to our demo file, here's the type of comment that you need to add at the beginning of a plugin. So that's what you need to add to your plugin to make sure that WordPress knows that this is a plugin and displays the correct text in the plugin screen in your WordPress admin screens. So let's move on to looking at some different types of comments that don't use multi lines. The first one is a single-line comment, which you do by adding two slashes. And the other thing you can do is add a single-line comment after your code. Again, making sure I spell correctly. So that comment will be skipped by WordPress. But it's useful sometimes if you want to add a comment after a piece of code to describe what it does, or maybe to make a note about some changes that you need to make to that code. Now you can also use single-line comments to stop code from running. So let's say we've got that Hello World again, But it's not working, you want to debug it. You can simply add the two slashes to comment that out and stop it from running. Now what you would find here, it would just echo nothing. If you actually wanted to stop it from echoing, you'd put the two slashes at the beginning. So that effectively deletes that line of code without actually deleting it. It means that you can stop it from running without removing it from your file, which is really useful for debugging. You can also stop multiple lines of code from running by including them in a multiline comment. And then once I've got it working again, by editing that, I can switch off my comments. But I'm gonna leave that there, making sure I do them in the right order, So that it's in our demo file. So that's how you add comments either around multiple lines of PHP or on a single line. What if you're on a PHP file but you're not actually in PHP? So you've moved out to be working in HTML. Well, in that case you use the standard HTML commenting syntax. So that's how you add a comment there. And then if you need to go into PHP you open them up again, oops. So those are some examples of how you use comments in WordPress. In the next part of the course, we'll move on to looking at functions, and I'll show you how to write a function in PHP. See you next time, and thanks for watching.