Commented Out Code

ID

php.commented_out_code

Severity

info

Remediation Complexity

trivial

Remediation Risk

low

Remediation Effort

low

Resource

Code Smell

Language

Php

Tags

code_smell, dead-code

Description

Reports blocks of commented-out source code: a run of consecutive // or # line comments, or a /* …​ */ block comment, whose contents parse as PHP statements rather than prose.

Rationale

Commenting code out instead of deleting it is a common habit, but the disabled code quickly becomes dead weight: it goes stale, misleads readers about what the program actually does, and clutters diffs and searches. Version control already preserves the full history, so the old code can always be recovered when needed. The rule uses the PHP parser as the deciding oracle — only a block that actually parses into statements is flagged, so genuine prose comments and documentation blocks are left alone.

<?php
class Processor
{
    public function handle(int $x): int
    {
        // $total = $this->compute($x);   // FLAW — commented-out statements
        // $total = $total * 2;
        // return $total;

        // This method computes the total // OK — prose, not code
        // for the current user account

        return $this->compute($x);
    }
}

Remediation

Delete the commented-out code. If it is needed later, recover it from version control. When the intent is to document why a block is disabled, replace it with a short prose comment explaining the reasoning instead of keeping the dead statements.

References