How to Easily Protect your Code Base from Commented PHP Code

2021-08-02

When it comes to merging huge pull-request, here and there, a bit of commented code slips to our codebase. Do you trust your reckless developers to check every single line? Are you sure?

We cherish our developers' attention so we come with a simple solution that we added to our CI. Now we know for sure. Do you think you have 0 % unwanted commented code? I dare you to have more.

With following approach, we've discovered more than 150 commented out PHP lines in Rector code today:

How we Detect Commented PHP Code Today?

The "best" way to detect commented code was with a sniff from PHP_CodeSniffer. It parsed every token in a comment and tried to decide if it's a commented PHP code, an example of PHP code, or normal text. It is instead a complex process with lots of false positives.

Is this PHP code?

// if useful, remove

Or this one?

// for example
// $value = 1000;

Re-Define the "Commented PHP Code"

We had such a sniff, and it was not working correctly. We stopped to think about the problem. How does commented PHP code look like? Let's say we have this code:

private function resolveFromNodeAndType(Node $node, Type $type): ?string
{
    $variableName = $this->resolveBareFromNode($node);
    if ($variableName === null) {
        return null;
    }

    $stringy = new Stringy($variableName);
    return (string) $stringy->camelize();
}

What happens when you try to comment it out in PHPStorm?

//private function resolveFromNodeAndType(Node $node, Type $type): ?string
//{
//    $variableName = $this->resolveBareFromNode($node);
//    if ($variableName === null) {
//        return null;
//    }
//
//    $stringy = new Stringy($variableName);
//    return (string) $stringy->camelize();
//}

What has changed? Every line starts with //.

What do we use if we want to comment logic and explain behavior? The doc block:

/**
 * If used on Monday, produces this code:
 *    $value = 'Monday is here';
 *    finally;
 * The rest of the week is off
 */

In the end, all we look for is a more significant amount of lines starting with //.

// ...
// ...
// ...

After we re-defined the problem to a much simpler one, it was pretty easy to add this command to symplify/easy-ci utils package.

3 Steps to Detect Commented PHP Code in Your CI

1. Install Easy CI

composer require symplify/easy-ci --dev

2. Run it

vendor/bin/easy-ci check-commented-code <directory|ies>
vendor/bin/easy-ci check-commented-code src packages

Is it too strict? Tune line limit to your needs:

vendor/bin/easy-ci check-commented-code src packages --line-limit 10

3. Add it to your CI

That's it!

Happy coding!

Do you learn from my contents or use open-source packages like Rector every day?
Consider supporting it on GitHub Sponsors. I'd really appreciate it!