> ## Content Index
> Fetch the complete content index at: https://stalin-pereira.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# Your Code Comments Are Useless: Writing Documentation That Future You Will Thank You For
- URL: https://stalin-pereira.com/your-code-comments-are-useless-writing-documentation-that-future-you-will-thank-you-for/
- Published: 2026-01-24T04:44:00.000Z
- Updated: 2026-10-16T19:08:18.000Z
- Description: Distinguishing between worthless what-comments and valuable why-comments with real examples
- Author: Stalin Pereira
- Tags: Developer Practices

**Your Comments Are Lying**

Why future you will curse present you

## Imagine Reading Your Diary

From 3 years ago with zero context

- **No Memory** — You forgot why you made that decision
- **Cryptic Notes** — Past you left breadcrumbs that lead nowhere
- **Time Lost** — Hours spent reverse-engineering your own work

## Code Comments Work The Same

Most developers comment the wrong things entirely

- **What vs Why** — 90% of comments explain what code does, not why
- **Redundant Info** — The code already tells you what it does
- **Missing Context** — Business decisions and constraints vanish forever

## The Useless Comment Graveyard

Real examples that help absolutely no one

- **Increment Counter** — Comment above: i++ says 'add one to i'
- **Get User** — Function comment: 'This function gets the user'
- **Loop Through** — Comment: 'Loop through the array' above a for loop

## Why These Comments Fail

They describe the obvious while hiding the important

- **Zero Value** — Anyone reading the code can see what it does
- **Maintenance Debt** — Comments rot faster than code when things change
- **False Confidence** — Developers think the code is documented when it isn't

## Comments That Actually Matter

The why behind the what changes everything

- **Business Rules** — Why this calculation uses 1.7 not 2.0 multiplier
- **Edge Cases** — Why null check exists after a weird production bug
- **Constraints** — Why we can't use the obvious solution here

## Old Way vs New Way

Transform worthless comments into valuable ones

- **Old Way** — Calculate total price - multiply quantity by price
- **New Way** — Tax excluded per finance team request, added at checkout
- **The Difference** — One repeats code, one explains business context

## The Why Comment Framework

Four questions to ask before writing any comment

- **Why Not Simpler?** — Explain why the obvious approach doesn't work here
- **Why This Value?** — Document magic numbers and their business origin
- **Why Now?** — Link to the bug ticket or incident that caused this
- **Why Here?** — Explain architectural decisions that aren't obvious

## Real Business Impact

Good comments save real time and money

- **Onboarding Speed** — New developers understand intent in minutes not days
- **Fewer Regressions** — Devs won't accidentally break undocumented edge cases
- **Faster Debugging** — Why-comments point directly to root cause context

## The Golden Rule

One principle to transform your documentation forever

- **Code Shows How** — The syntax and structure reveal implementation
- **Comments Show Why** — The reasoning and context live only in comments
- **Tests Show What** — Expected behavior is documented through test cases

## Write For Strangers

Future you is a stranger who forgot everything

> Before your next commit, ask: Would a stranger understand WHY this code exists?

---

What's the most useless comment you've ever seen in a codebase? Drop it below!