Commenting out your PHP Code
There are 2 methods to commenting out your PHP. You can add double slashes // some code here to the beginning of each line, or you can wrap the entire code in a docblock /** some code here **/. I prefer the double slashes approach because it gives you more control.
Do you ever need to know how to comment out your PHP code because something appears to be broken, but you don’t know what? Commenting out code is a good way to test new logic without completely removing old logic that you’re not quite ready to delete.
Option 1: Using docblocks to comment out sections of PHP code
A common way to comment out code in PHP is to use docblocks around the code. You surround the code in the following syntax /** {code here} **/ and it will comment out everything inside of that section.
Here is an example of code commented out through a docblock
<?php
$pieList = ["apple", "blueberry", "pecan"];
/**
foreach ($pieList as $pie) {
echo "This pie is $pie";
}
**/
$drinkList = [];
?>In the above example, we wrapped the foreach loop around a set of docblocks. This enabled us to skip the entire step where we looped over the list of pies and echoed each one.
The benefit of using this approach is that you can quickly comment out bigger blocks of code easily. You don’t have to go line by line as you will see in the next approach. If you know that there are continuous lines of code that you want to comment out, then you could save some time and energy by using this approach.
Concerns with commenting out PHP code in docblocks
Ok, so is the docblock solution the only or even the right solution to commenting out your code. The answer is unlikely. The benefits of this option is also the drawbacks and points of concern.
#1 – Large comment blocks can include unintended code
<?php
function makePies(string $pie) {
PieList = ["apple", "blueberry", "pumpking"];
/**
foreach ($pieList as $key => $val) {
echo "Key is: " . $key;
if (in_array($val, $pieList)) {
echo "Yummy pie: " . $val;
}
}
}
**/The above commented out PHP code contains an error? Do you spot it? I added the closing docblock after the end of the function but the opening of the docblock is inside of the function.
This issue does happen more than you may realize. You’re generally commenting out large sections of logic when you choose the docblock approach. You are likely commenting out a large function or loop that consists of a sizable amount of logic. You scroll to the top and add the opening to the docblock, then scroll to the bottom and apply the docblock to what you think is the end
You save, and run it… Boom, your application crashes, and now you’re distracting by debugging a new issue when you commented out your code as opposed to working on your original issue.
#2 – Commented out code with docblocks cannot include already documentation notes.
<?php
/**
function eatThisPie(string $pie) {
/** we want to check whether the person
wants the pies before eating it.
**/
return in_array($pie, ["apple", "blueberry", "pecan"]);
}
**/Do you see the bug inside of this code? What’s going to happen if I save it and then run my application? The first closing docblock will actually include anything wrapped between it and then opening docblock. This includes the start of the second docblock.
This means that the return, closing bracket and ending docblock will be randomly inserted into the application. Your app will scream at you when you try to run the above code.
Option 2: Use double forward slashes to comment out single lines
The safest method to commenting out code is actually going to the beginning of each line, and add double forward slashes // .
<?php
// function runWithIt() {
// .. Do some logic here ...
// } I know. You’re first response is that this is fine with a little bit of code, but what if I need to comment out 50+ lines of code? This is going to be really tedious.
It’s true that it takes more time up-front to comment on each line, but you will save a large amount of time later when trying to debug your commented-out code when running the application.
Review your commented code
Using the above approach forces you to review the code your commenting. Using docblocks to comment out large amounts of PHP code makes it too easy to skip a step of actually reviewing the code. You may discover that there are sections that you don’t want comment or that you can’t comment a particular few lines.
Review the docblock bug examples again and imagine using double forward slashes in those scenarios. Do you think that those bugs would’ve been prevented?
Most likely.
I know that a big belief for developers is to avoid redundancies and save as much as time as possible. This is true and it may feel like the double forward slashes are very redundant, but it is not the full picture.
It is more important to not chase rabbit holes by introducing unnecessary bugs through docblocks when you could prevent hours long time sinks by using double forward slashes //
Don’t leave commented out code inside your files
You may be tempted to save and leave commented out code inside of your codebase, because you may need to come back to it later. You have good intentions but this is a bad idea.
Remove all commented out code before pushing up to your repository. Historical records is a huge part of why you use GIT or other version control. Trust your repository. You can easily look at Github at past versions of your code.
The reason why that you don’t want to leave commented out code is that you will forget about it in a week and have made your file much harder to read for the next person to open. If you continued with this practice, your files will filled with more commented code then real code, and you will probably have no idea why you commented it or what it did in 6 months.
I get it. Many times, you’re not quite settled on some code and logic. It can also be tempting when the business request doesn’t make sense and you know that they will go back to the original. Why erase something that could come back soon?
This is still a bad idea. A good diff tool provided by your repo managing service whether Github, Gitlab, Bitbucket or whatever is light years better than what you can do. It’s a visual reference that showcases the changes that you made.
Let’s say you did need to come back to the code and uncomment it. You commented code at lines 42-46, 12, and 62-75. What are the chances that you would forget what all you commented out? Probably pretty high. Now, compound the situation because you still have uncommented code from an update you made 6 months ago.
See where this is headed?
Be careful with your code when commenting it out in PHP
It wasn’t intentional but I was much more cautious in this article over other articles in here that I’ve written. In the end, you will need to comment out portions of your code, but just be careful in your practice of it. There are quick ways to commenting out your code in PHP and then there are smarter ways to code comment. This is a good example where the right solution isn’t always the simplest.
Comment out your php code as much as you need, but just be prudent in what you comment and leave behind.
