Yes, your code does need comments

I’m going to say something you might disagree with: your code needs comments.

I know, I know. You’ve heard it before—“good code is self-documenting” and “if you need comments, your code isn’t clean enough.” But hear me out.

The Comment Trap

First, let me be clear about what I’m not advocating for. Comments that simply restate what the code does are useless:

# increment i by 1
i += 1

This adds nothing. Code is far better at describing what code does than English, so just write clear code. On this point, I agree with the critics.

Comments as Documentation

What I am advocating for is using comments to document your code. Comments should explain:

• Complex code blocks that aren’t immediately obvious
• Why functions and classes exist
• The original intent behind decisions

Take a look at Zed Shaw’s Lamson project. It’s some of the best documented Python code I’ve seen. Every module, class, and function has clear documentation explaining its purpose.

Capturing Intent

Here’s the key insight: comments capture intent.

Code can only tell you what it does right now. It can’t tell you what the original developer was thinking, or why they made certain decisions. Comments preserve that context.

When you come back to code six months later—or when a new team member is trying to understand it—those comments explaining why are invaluable. They help you:

1. Understand the original meaning quickly
2. Avoid breaking things when making changes
3. Reduce cognitive load when solving problems

Some Guidelines

Here are five rules I try to follow:

1. Use clear, unambiguous class and function names
2. Add inline comments on complicated code blocks
3. Use descriptive variable names
4. Document why code exists, not just what it does
5. Keep comments updated when you change code

Conclusion

Code clarity and documentation comments aren’t competing concerns—they’re complementary. Write clean code and document your intent. Your future self will thank you.