Why I Write Code Comments

Future you will thank present you. Thoughts on documentation as a form of kindness to your future self and collaborators.

Comments aren't clutter—they're context.

The Argument Against

"Good code documents itself." You've heard this. Maybe you've said it.

And it's partially true. Clear variable names, well-structured functions, and proper abstractions do communicate intent.

But they don't tell you *why*.

What Comments Should Explain

Not *what* the code does—that should be obvious. But:

• **Why this approach** over alternatives
• **What problem** this solves
• **What assumption** the code makes
• **What gotcha** to watch out for

A Real Example

```typescript // Bad: States the obvious // Loop through users users.forEach(user => { ... })

// Good: Explains the why // Process users in sequence to avoid rate limiting // Parallel processing caused 429 errors in production for (const user of users) { ... } ```

Comments as Time Travel

Every comment is a message to the future. When you return to this code in six months, will you remember:

• Why you chose this algorithm?
• What edge case you're handling?
• What you tried that didn't work?

Your future self is a collaborator. Treat them well.

The Best Comment

Sometimes the best comment is the one that says "I know this looks weird, here's why."

It's permission for the next person (including future you) to understand without judgment.

Write Them

Yes, they can get stale. Yes, they add lines. Yes, good naming helps.

But comments are documentation, and documentation is kindness. Be kind to your future self.