check-comments

Comment Quality Check

Analyze PHP code for documentation and comment issues.

Detection Patterns

1. Missing PHPDoc

// BAD: No documentation on public method
public function process(array $items, bool $force = false): Result
{
}

// GOOD: Documented public method
/**
 * Process items with optional force flag.
 *
 * @param array<Item> $items Items to process
 * @param bool $force Force processing even if already processed
 * @return Result Processing result with status and errors
 *
 * @throws ProcessingException When processing fails
 */
public function process(array $items, bool $force = false): Result
{
}

2. Outdated Comments

// BAD: Comment doesn't match code
// Calculates the discount percentage
public function calculateTax(Money $amount): Money
{
    return $amount->multiply(0.21);
}

// BAD: TODO that's been done or is stale
// TODO: Add validation (added 3 years ago)
$this->validate($data);

// BAD: Incorrect parameter documentation
/**
 * @param string $userId The user ID  // Actually int
 */
public function findUser(int $userId): User {}

3. Commented-Out Code

// BAD: Dead code cluttering the file
public function process(Order $order): void
{
    // $this->legacyProcessor->process($order);
    // if ($order->needsSpecialHandling()) {
    //     $this->specialHandler->handle($order);
    // }

    $this->newProcessor->process($order);
}

// Remove commented code - use version control instead
public function process(Order $order): void
{
    $this->newProcessor->process($order);
}

4. Obvious Comments

// BAD: Comments stating the obvious
// Get the user
$user = $this->getUser();

// Increment counter
$counter++;

// Loop through items
foreach ($items as $item) {}

// GOOD: Comments explaining WHY
// Fetch fresh user to ensure permissions are current
$user = $this->getUser();

5. Self-Documenting Code Opportunities

// BAD: Comment needed due to unclear code
// Check if user can access premium features
if ($user->level >= 3 && $user->subscription !== null && $user->subscription->isActive()) {}

// GOOD: Self-documenting
if ($user->canAccessPremiumFeatures()) {}

// BAD: Magic number with comment
// 86400 seconds in a day
$expiry = time() + 86400;

// GOOD: Named constant
$expiry = time() + self::SECONDS_PER_DAY;