PHP Comments

let's now dive into PHP comments—these simple but super important integral parts of PHP coding. You can think of comments as small notes or hints you leave either for yourself or others in your code. That might sound a little basic, but here's the thing: comments can save you a lot of headaches down the road. Whether you're just getting started or are a longtime coder, knowing how to use comments effectively is a game-changer.

Why Do We Even Need Comments?

I know what you're thinking: "I'll just remember what my code does!" But trust me, after having written hundreds, or thousands of lines of code, it is not quite that simple. A week later, you may look at something you've written and think: "What was I thinking here?" That's when comments become handy.

They're like friendly reminders about what your code is supposed to do, why you wrote it a certain way, or even things you still need to work on.

Let me break it down even more. Comments can help in a few key situations:

The Basics of Writing PHP Comments

Fine, now that you understand why comments are so useful, it is time to discuss how to write them in PHP, actually. There are two major types of comments in PHP: single-line comments and multi-line comments.

Single-Line Comments

These are exactly what they sound like: comments that take up just one line. You use them when you want to make a quick note or explanation about a specific line of code. In PHP, you've got two ways to write single-line comments. You can either use // or #. Both work the same way so you can choose whichever you prefer.

Here's what they look like:

// This is a single-line comment in PHP
# You can also use a hash for a single-line comment

Notice anything you write after // or # gets ignored by PHP, the computer doesn't try to run it, it's just there for you or any other human reading the code.

Multi-Line Comments

Sometimes one line just isn't enough. If you've got more to say, like explaining a bigger chunk of code or writing down to-do lists you can use a multi-line comment. Multi-line comments start with /* and end with */.

Here is an example:

/*
This is what a multi-line comment looks like.
It can go on for several lines.
PHP ignores everything between the /* and */

These are great when you want to explain something in a bit more detail. But be careful not to go overboard. A comment longer than your actual code is probably less helpful than you think. Keep it concise and relevant.

When (And When Not) To Use Comments

It might sound tempting to sprinkle comments everywhere, but there's an art to using them wisely. You don't want your code cluttered with comments on the obvious. The key is finding a balance like in most things—writing enough comments to make the code easy to follow but not so many that they're distracting.

Here's a good rule of thumb:

Examples

Suppose you are working on a PHP script intended for a basic website to show various contents depending on time. Here is a basic version of that code without comments:

$hour = date("H");

if ($hour < 12) {
    echo "Good morning!";
} elseif ($hour < 18) {
    echo "Good afternoon!";
} else {
    echo "Good evening!";
}

It's not too complex, but just put yourself in a situation where you need to come back to this code in, say, a few months. Would you know exactly why you chose those times of the day? Maybe not. Now, let's add some comments and make sense of this:

$hour = date("H"); // Get the current hour in 24-hour format
// Check the time and display the appropriate greeting
if ($hour < 12) {
    echo "Good morning!"; // Before 12 PM
} elseif ($hour < 18) {
    echo "Good afternoon!"; // Between 12 PM and 6 PM
} else {
    echo "Good evening!"; // After 6 PM
}

Now, with comments, it is a lot easier to see what this code is actually doing, and why. Your future self will thank you!

Commenting Out Code to Debug

One of the cool things about comments is that you can use them to comment out code. That is, you can temporarily disable certain parts of your code without having to delete it. It's like hitting pause on a specific section while you figure something out.

Here's how it works. Suppose that you are in a position where you are debugging a script and you suspect one of your echo statements is the culprit. You can 'comment out' like this:

echo "This is working fine.";

// echo "This is causing an error. I'm commenting it out for now.";

echo "Still running fine.";

With the simple change of making that second echo a comment, PHP will skip over executing it but the code is still there should you want to bring it back later. It saves you from having to rewrite code if you are just testing things out.

PHPDoc: A Special Kind of Comment

Now, if you are working on bigger projects or in teams, you may be introduced to something called PHPDoc. It's this special breed of comment that allows you to comment on your functions, classes, and methods in a better-structured way. But it doesn't stop there, tools can actually read these comments and automatically create your documentation for you. Isn't that neat?

Here's a simple example of what PHPDoc might look like:

/**
 * Adds two numbers together.
 *
 * @param int $a The first number.
 * @param int $b The second number.
 * @return int The sum of the two numbers.
 */
function addNumbers($a, $b) {
    return $a + $b;
}

These sorts of comments are very useful if you're working on large projects or sharing your code with others. They provide a good amount of detail about what each portion of the function does, and tools can actually read them to create a full documentation file for your code.

Here are the most common parameters for PHPDoc commenting:-

And so many other keys to define the source code description. You can see more from here.

That’s all. Let’s summarize it.

Wrapping Up

There you have it, a deep dive into the world of PHP comments. While they are seemingly a minor thing, they may make all the difference in how easily you or someone else will be able to work with that code later on. Comments are not just for others but for your own benefit. Think of them as little breadcrumbs, enabling you to find your way back if your code turns out to be some kind of maze.

Thank you for reading. Happy Coding!