Code Reading

Why Read Code?

To improve your coding skills, read code created by skilled developers.

Read well-made open source projects for each language to learn how to code properly in that language.

What You Learn

There are many attributes of software code that you will learn by reading existing code:

  • Indentation: Proper formatting and structure
  • Comments: How to document code effectively
  • History Header: Version and change tracking
  • Function Structure: How to organize and structure functions
  • Architecture Patterns: Common design patterns in practice
  • Error Handling: Best practices for handling errors
  • Testing Approaches: How experienced developers test their code

How to Practice

  1. Choose a well-regarded open source project in your target language
  2. Start by reading the main entry points
  3. Follow the flow through the codebase
  4. Take notes on patterns you observe
  5. Try to understand why certain decisions were made
  6. Apply what you learn to your own projects

Different languages have exemplary projects that showcase idiomatic patterns and clean architecture:

Language Project Why It’s Good
Java Spring Framework Clean abstractions, extensive use of design patterns
Python Requests Beautiful API design, readable code
Go Docker Idiomatic Go, well-structured large project
Kotlin OkHttp Clear separation of concerns, excellent test coverage
JavaScript Express.js Minimal yet powerful middleware architecture
Rust Ripgrep Performance-focused design with clean code

Strategies for Effective Code Reading

Start with Tests

Test files are often the best documentation. They show how the code is intended to be used and what edge cases the developers considered. Reading test files first gives you a mental model of the expected behavior before diving into implementation details.

Use the Debugger

Rather than just reading code statically, step through it with a debugger. Set a breakpoint at the entry point and follow the execution flow. This reveals the actual runtime behavior, including polymorphic dispatch and dependency injection that can be hard to trace by reading alone.

Read in Layers

For large codebases, adopt a layered reading approach:

  1. Surface level: Read the README, documentation, and project structure to understand the high-level purpose
  2. API level: Examine the public interfaces and how they are designed
  3. Implementation level: Dive into the internals of specific modules
  4. Detail level: Study individual algorithms and data structures

Track Your Observations

Keep a notebook or document where you record:

  • Patterns discovered: Design patterns, idioms, and conventions used
  • Questions raised: Things you don’t understand yet
  • Ideas to apply: Techniques you want to use in your own code
  • Mistakes found: Even great projects have imperfect code — recognizing issues sharpens your review skills

Common Pitfalls in Code Reading

  • Trying to understand everything at once: Focus on specific modules or features rather than attempting to comprehend the entire codebase
  • Ignoring the history: Use git log and git blame to understand why code was written a certain way. A seemingly odd design decision might make sense when you see the commit message explaining a bug fix
  • Not running the code: Always clone the project, build it, and run the tests. Seeing code execute makes it much easier to understand
  • Skipping documentation: Comments, doc strings, and architectural decision records contain valuable context that is not apparent from the code alone

Making Code Reading a Habit

Reading code is a skill that improves with consistent practice. Consider dedicating time each week to reading code:

  • Daily: Spend 15 minutes reviewing a pull request from a colleague or an open source project
  • Weekly: Read through a module or feature in a project you admire
  • Monthly: Study the architecture of a new open source project

Over time, code reading builds an intuition for good design that no amount of tutorial-following can replicate. You begin to recognize patterns instantly and develop a sense for when code “smells” wrong, making you both a better writer and reviewer of code.