Ask Claude to Add "Why" Comments to Complex Code That Future Developers Will Thank You For

Self-documenting code tells you what happens. Comments tell you why it happens that way. When code is complex enough that the "why" isn't obvious, Claude can add the missing context.

> read the pricing calculation in app/Services/PricingService.php
> and add inline comments explaining the reasoning behind any
> non-obvious logic — why decisions were made, not what the code does

Claude reads the implementation, identifies the parts where the reasoning isn't self-evident, and adds comments that explain the intent:

// Apply discount before tax — required by EU VAT regulations
// where the taxable amount must be the discounted price
$taxableAmount = $subtotal - $discount;

// Round to nearest cent AFTER all calculations, not during —
// intermediate rounding causes penny discrepancies on large orders
$total = round($taxableAmount + $tax, 2);

// Process refunds synchronously even though charges are async —
// Stripe requires the original charge to be settled before
// issuing a refund, and our webhook handler depends on this order
$this->processRefund($charge);

Notice how none of these comments describe what the code does — the code itself is clear. They explain why it does it that way, which is the part that gets lost over time.

Ask Claude to target specific areas:

> add comments to the SQL query explaining why each JOIN
> is needed and what data it brings in

> explain the regex pattern in a comment — what it matches
> and why that specific pattern was chosen

> add a comment to each config value explaining what breaks
> if it's changed and what the valid range is

Claude is especially good at this for code it didn't write — it reads the implementation objectively and identifies the parts where a reader would naturally ask "but why?" Then it answers that question in a comment.

Code tells you how. Comments tell you why. Let Claude add the "why" before it's forgotten.

via Claude Code