Imagine watching a silent movie with no title cards — you have no idea what’s happening. Now imagine a movie where every 10 seconds a card appears explaining what you just saw — equally annoying. Comment Ratio measures the percentage of lines that are comments compared to total code+comment lines.
We scan the raw file lines and classify each line as either code, comment, or blank. The ratio is comments / (code + comments). If the ratio is below the minimum (default 10%), the code is underdocumented. Above the maximum (default 50%), the code is overcommented, which can indicate unclear code that needs excessive explanation.
No one knows why this code exists.
class PaymentProcessor
{
public function execute(): void
{
$this->validate();
$this->charge();
$this->notify();
}
}
Every line explained — the comments are louder than the code.
class PaymentProcessor
{
/**
* Processes a payment by validating, charging, and notifying.
* This method is the main entry point for payment processing.
* It orchestrates the three step payment workflow.
*/
public function execute(): void
{
// Step 1: Validate the payment input
$this->validate(); // Check if the input data is valid
// Step 2: Charge the customer
$this->charge(); // Process the payment with the gateway
// Step 3: Notify the customer
$this->notify(); // Send the confirmation email
}
}
Comments explain why, the code shows how.
/**
* Processes payments through the configured gateway.
* Supports credit cards and wire transfers.
*/
class PaymentProcessor
{
public function execute(): void
{
$this->validate();
$this->charge();
$this->notify();
}
}
rules:
E0026:
min_ratio: 0.1
max_ratio: 0.5
If Phanalist flags low comment ratio, your code is missing context for future maintainers. If it flags high ratio, your code might be too hard to understand — simplify it instead of explaining it.