We spend more time reading code than writing it. Here's how to get better at it.

The Uncomfortable Truth

Most of your job is reading code:

  • Understanding what exists before changing it
  • Reviewing others' code
  • Debugging production issues
  • Learning from open source

Yet tutorials focus on writing. Reading is the neglected skill.

How to Approach Unfamiliar Code

1. Start with the entry point

# Find main or entry
grep -r "def main" .
grep -r "__main__" .
grep -r "app.run" .

Follow the execution path from there.

2. Read the tests

Tests show how the code is meant to be used:

def test_user_creation():
    user = User(name="Alice", email="alice@example.com")
    assert user.is_valid()

This tells you more than reading the User class directly.

3. Focus on one path

Don't try to understand everything. Pick one feature or flow:

  • "How does user login work?"
  • "What happens when an order is placed?"
  • "How does this API endpoint process requests?"

Follow that path, ignore the rest.

4. Use your tools

# Find where something is defined
grep -rn "def process_order" .
 
# Find where something is used
grep -rn "process_order(" .
 
# Jump to definition (in IDE)
Cmd+click / F12

5. Draw as you go

Request → Router → Handler → Service → Database
                       ↓
                   Validator

Even rough diagrams clarify flow.

Reading Strategies

Depth-first

Pick one function. Understand it completely. Then move to what it calls.

Good for: Debugging, understanding specific behavior.

Breadth-first

Skim all files in a directory. Get a sense of structure. Then dive deeper.

Good for: New codebases, architectural understanding.

Test-first

Read the tests before the implementation. Understand expected behavior before how it's achieved.

Good for: Libraries, well-tested code.

Signs of Readable Code

When reading, notice what makes code easy or hard:

Easy to read:

  • Clear function names
  • Small functions
  • Obvious flow
  • Helpful comments on why

Hard to read:

  • Clever tricks
  • Deep nesting
  • Surprising side effects
  • Misleading names

File these observations. Apply them to your own code.

Common Patterns to Recognize

Learn to spot patterns quickly:

# Factory
def create_handler(type):
    return handlers[type]()
 
# Decorator
@retry(times=3)
def fetch_data():
    ...
 
# Context manager
with transaction():
    update_database()
 
# Strategy
class PaymentProcessor:
    def __init__(self, strategy):
        self.strategy = strategy

Pattern recognition speeds up reading.

Questions to Ask

When reading code:

  1. What does this do? (behavior)
  2. Why does it do it this way? (design decisions)
  3. What assumptions does it make? (constraints)
  4. Where might it break? (edge cases)
  5. How would I test this? (verification)

Practice Reading

Deliberately read code to improve:

  • Open source: Read projects you use
  • Code review: Review even if not assigned
  • Debugging: Read before using the debugger
  • Refactoring: Understand before changing

My Process

  1. Find entry point
  2. Trace one path through the code
  3. Note what I don't understand
  4. Read tests for those parts
  5. Draw the flow
  6. Re-read with new understanding

Usually takes 2-3 passes to feel comfortable.

The Payoff

Good code readers:

  • Debug faster
  • Review more effectively
  • Learn from others
  • Make better design decisions

Reading is a skill. Practice it intentionally.

React to this post: