DEV Community: Aaron Rose

The Secret Life of Go: Error Handling (Part 2)

Aaron Rose — Fri, 20 Mar 2026 07:31:47 +0000

Data-Rich Errors, Custom Structs, and errors.As

Eleanor is a senior software engineer. Ethan is her junior colleague. They work in a beautiful beaux arts library in Lower Manhattan — the kind of place where coding languages are discussed like poetry.

Episode 31

Ethan was building a user registration endpoint. He had learned his lesson from the previous day and was dutifully avoiding string matching.

"I have a problem with Sentinel errors," Ethan said, turning his monitor toward Eleanor. "They are great for simple states like ErrNotFound. But what if the error is a validation failure? I need to tell the frontend exactly which field failed and why. I can't write a Sentinel variable for every possible bad email address."

He showed her his workaround:

// Ethan's attempt to return data
func validateUser(u User) (string, string, error) {
    if !strings.Contains(u.Email, "@") {
        return "email", "missing @ symbol", errors.New("validation failed")
    }
    return "", "", nil
}

Eleanor winced slightly. "You are returning the error details separately from the error itself. That breaks the standard Go function signature. What if this error needs to bubble up through three different functions before the HTTP handler catches it? Do they all have to return (string, string, error)?"

"That's exactly why I'm stuck," Ethan admitted. "An error in Go is just a string interface. How do I put structured data inside it?"

The Custom Error Struct

"An error in Go is not just a string," Eleanor corrected gently. "It is an interface with a single method: Error() string. That means any struct can become an error, as long as it implements that method."

She opened a new file and defined a custom struct:

// ValidationError holds structured data about what went wrong.
type ValidationError struct {
    Field  string
    Reason string
    Err    error // The underlying wrapped error (optional, but good practice)
}

// Implement the error interface
func (v *ValidationError) Error() string {
    return fmt.Sprintf("validation failed on %s: %s", v.Field, v.Reason)
}

// Implement the Unwrap interface so errors.Is and errors.As can look inside it
func (v *ValidationError) Unwrap() error {
    return v.Err
}

"Now," Eleanor said, "your validation function can just return a standard error, but underneath, it is secretly passing a rich data structure."

func validateUser(u User) error {
    if !strings.Contains(u.Email, "@") {
        // We return a pointer to our custom struct
        return &ValidationError{
            Field:  "email",
            Reason: "missing @ symbol",
        }
    }
    return nil
}

The Extraction (`errors.As`)

Ethan looked at the calling code in his HTTP handler. "Okay, so validateUser returns an error interface. How do I get my Field and Reason back out of it? errors.Is just returns a boolean."

"If errors.Is is for checking identity, errors.As is for extracting data," Eleanor explained.

She wrote the extraction logic in his HTTP handler:

err := validateUser(newUser)
if err != nil {
    // 1. Create an empty pointer of your custom error type
    var valErr *ValidationError

    // 2. Ask Go: "Is there a *ValidationError anywhere inside this error chain? 
    // If so, unpack its data into my valErr variable."
    if errors.As(err, &valErr) {
        // 3. We now have fully typed access to the struct's fields!
        response := map[string]string{
            "error":  "invalid input",
            "field":  valErr.Field,
            "reason": valErr.Reason,
        }
        return sendJSON(w, 400, response)
    }

    // Fallback for unexpected errors
    return sendJSON(w, 500, "internal server error")
}

Ethan stared at the errors.As(err, &valErr) line. "It's like a type assertion, but better. If I used a standard type assertion like err.(*ValidationError), it would fail if the error had been wrapped with %w somewhere along the way."

"Exactly," Eleanor smiled. "Because of the Matryoshka doll wrapping we learned yesterday, a simple type assertion only looks at the outermost doll. errors.As opens up every single doll in the chain until it finds a struct that matches the type of valErr. If it finds one, it populates your variable and returns true."

The Architect's Rule

Ethan leaned back, looking at his clean, structured HTTP handler. "This is a game-changer. I can pass HTTP status codes, retry hints, and validation fields right inside the error itself."

"You can," Eleanor agreed. "But remember the distinction. Use Sentinel Errors (with errors.Is) for state—answering the question 'What happened?'. Use Custom Error Structs (with errors.As) for data—answering the question 'What are the details?'."

Ethan deleted his messy (string, string, error) return values. The Go error interface wasn't a limitation anymore; it was a carrier pigeon, perfectly capable of delivering whatever payload he needed, safely and strictly typed.

Key Concepts Introduced:

The error Interface

In Go, an error is any type that implements Error() string. By creating a custom struct and attaching this method, you can build errors that carry rich, structured data (like HTTP status codes or validation fields).

The Unwrap Method

If your custom error struct wraps another error, you should implement Unwrap() error. This allows Go's standard library functions to look "inside" your struct when searching the error chain.

errors.As vs. Type Assertions

A standard type assertion err.(*MyError) will fail if the error was wrapped (e.g., using fmt.Errorf("... %w", err)).
errors.As(err, &myErr) traverses the entire error chain, unwrapping each layer. If it finds a type match anywhere in the chain, it populates your target variable and returns true.

The Architect's Rule of Error Handling

Identity: Use Sentinel variables and errors.Is when you only need to know what happened (e.g., ErrNotFound).
Data: Use Custom Structs and errors.As when you need to know the details of what happened (e.g., ValidationError{Field: "email"}).

Aaron Rose is a software engineer and technology writer at tech-reader.blog. For explainer videos and podcasts, check out Tech-Reader YouTube channel.

The Secret Life of Go: Error Handling

Aaron Rose — Thu, 19 Mar 2026 05:15:45 +0000

Sentinel Errors, Wrapping, and The String Trap

Episode 30

Ethan was reviewing an HTTP handler he had just written. He wanted to return a 404 Not Found if a database query failed, and a 500 Internal Server Error for anything else.

"How does this look?" he asked, pointing to his screen.

user, err := db.GetUser(id)
if err != nil {
    // If the error message contains the words "not found", it's a 404
    if strings.Contains(err.Error(), "not found") {
        return respondWithError(w, 404, "User not found")
    }

    // Otherwise, it's a real server error
    return respondWithError(w, 500, "Internal server error")
}

Eleanor leaned in, her eyes scanning the strings.Contains line. "That," she said softly, "is a ticking time bomb."

"Why?" Ethan asked. "It works perfectly in my tests."

"It works today," Eleanor corrected. "But what happens next month when we update our database driver, and the library authors change their error message from 'record not found' to 'no rows in result set'?"

Ethan blinked. "My strings.Contains would fail. The app would start returning 500s instead of 404s, and pager alerts would go off at 3 AM."

"Exactly. Checking an error's string value is incredibly brittle," Eleanor explained. "In Go, an error isn't just a string for a human to read. It is a piece of state for your program to inspect."

The Sentinel Error

Eleanor opened the database package file. "Instead of relying on random text, a package should declare its specific failure states as exported variables. We call these Sentinel Errors—they stand guard, representing a specific, known failure."

She typed at the top of the file:

import "errors"

// ErrNotFound is a Sentinel Error. 
// It is exported (capitalized) so other packages can check against it.
var ErrNotFound = errors.New("record not found")

"Now," she said, switching back to the HTTP handler, "we check against the Sentinel using errors.Is."

user, err := db.GetUser(id)
if err != nil {
    // We ask Go: "Is this specific error inside the chain?"
    if errors.Is(err, database.ErrNotFound) {
        return respondWithError(w, 404, "User not found")
    }
    return respondWithError(w, 500, "Internal server error")
}

Ethan nodded. "That's much safer. If they change the text inside ErrNotFound later, my if statement still works because it's checking the memory address of the variable, not the string."

The Wrapping Problem (`%v` vs `%w`)

Ethan frowned at the screen. "But wait. If the database layer just returns ErrNotFound, the HTTP handler won't know which user ID failed. I need to add context to the error before I return it up the stack."

He quickly typed out a solution:

func GetUser(id int) (User, error) {
    // ... db lookup fails ...

    // Add context to the Sentinel error using fmt.Errorf and %v (value)
    return User{}, fmt.Errorf("failed to fetch user %d: %v", id, ErrNotFound)
}

"Don't do that!" Eleanor warned, catching his hand before he hit save.

"If you use %v (value) or %s (string), fmt.Errorf creates a brand new, flattened string. It destroys the original Sentinel Error. When your HTTP handler calls errors.Is(err, ErrNotFound), it will return false. The Sentinel is gone."

"So how do I add context without destroying the Sentinel?"

"You wrap it," Eleanor said, smiling. "Go 1.13 gave us a superpower. We use the %w verb."

She changed one character in his code:

func GetUser(id int) (User, error) {
    // ... db lookup fails ...

    // Use %w to WRAP the error
    return User{}, fmt.Errorf("failed to fetch user %d: %w", id, ErrNotFound)
}

"Think of %w like a Matryoshka doll," Eleanor explained. "It creates a new error with your helpful context ('failed to fetch user 42'), but it hides the original ErrNotFound securely inside it. It creates a linked list of errors."

"And errors.Is knows how to open the dolls?" Ethan asked.

"Exactly," Eleanor said. "When you call errors.Is(err, ErrNotFound), Go automatically unwraps the dolls, layer by layer, checking each one to see if it matches the Sentinel you are looking for."

Ethan looked at his refactored code. It was clean, type-safe, and completely immune to string-formatting bugs.

"I was treating errors like console logs," Ethan realized. "I was just formatting text."

"It's the most common mistake in Go," Eleanor agreed. "An error is an API. You are designing a programmable interface of failure states. Build it so the machine can read it, and the humans will be fine."

Key Concepts

The String Trap

Never use strings.Contains(err.Error(), "...") to determine your application's control flow. Error strings are meant for humans and logging; they are subject to change and will break your logic silently.

Sentinel Errors

A package-level, exported error variable (e.g., var ErrNotFound = errors.New("...")) used to indicate a specific, expected failure state.
Callers can use these variables to make decisions without relying on strings.

Error Wrapping (%w)

When returning an error up the stack, you often want to add context (e.g., "failed to open config file").
Using fmt.Errorf("... %v", err) destroys the original error type.
Using fmt.Errorf("... %w", err) wraps the error, creating a chain. The context is added, but the original error is preserved inside.

errors.Is

Replaces the old if err == ErrNotFound pattern.
errors.Is automatically unwraps the error chain (the Russian nesting dolls) and checks if the target Sentinel error exists anywhere in the chain.

Aaron Rose is a software engineer and technology writer at tech-reader.blog. For explainer videos and podcasts, check out Tech-Reader YouTube channel.

The Secret Life of Claude Code — The Language You Don't Know

Aaron Rose — Wed, 18 Mar 2026 03:23:30 +0000

How to work in an unfamiliar language with Claude Code — and where the limits of that partnership actually lie

Margaret is a senior software engineer. Timothy is her junior colleague. They work in a grand Victorian library in London — the kind of place where no one is expected to know everything, but everyone is expected to know what they don't know. Timothy has arrived today carrying a file he has never seen the like of before.

Episode 7

The File

He set the laptop on the table and turned it toward her without preamble. This, Margaret had learned, meant he wanted her to see something before he had fully decided what he thought about it.

She looked.

The file was Go. Thirty-eight lines, clean structure, a concurrency pattern using goroutines and channels. Well written, by the look of it.

"Yours?" she said.

"The platform team's. They want me to add retry logic to this service. Apparently I'm the only one available who isn't already overloaded." He paused. "I don't know Go."

Margaret looked at the file again. Then she looked at him.

"How much don't you know?"

"I mean — I can read the broad shape of it. It's clearly doing something with concurrent workers. But the channel syntax, the goroutine lifecycle, what happens when something panics — I don't know any of that with any confidence."

"And what did you do first?"

"I asked Claude Code to explain it to me."

"Good," Margaret said. "And what did it tell you?"

He turned the laptop back toward himself. "It explained the pattern clearly. Worker pool, jobs channel, results channel, WaitGroup for synchronisation. It said the retry logic should probably wrap the worker function and use a loop with a backoff." He looked up. "It made sense when I read it. But I don't know if I trust myself to implement it correctly in a language I've never written."

"That," Margaret said, "is exactly the right concern to have."

What Claude Code Can Do in a Language You Don't Know

"Let me be precise about what you have," Margaret said. "When you used Claude Code to explain that file, it gave you something genuinely valuable — a model of what the code does. The concepts, the pattern, the intent. That is real. You now understand the worker pool pattern in a way you didn't thirty minutes ago."

"It felt reliable," Timothy said. "The explanation matched what I could read."

"For well-established patterns in mature languages, Claude Code is very good at this. Go's concurrency model is not obscure — it is well documented, widely used, extensively written about. The explanation you received is likely accurate." She paused. "But there is a difference between understanding a pattern and being able to implement it correctly in a language you have never written. And that difference matters."

"Because I don't have the instincts yet."

"Because you don't have the instincts yet," she confirmed. "In your own language, when something feels wrong, you feel it. A variable name that's off. A pattern that doesn't fit. A return value being silently ignored. You have developed a sensitivity to the grain of the language over years of use. In Go, you have none of that. Everything feels equally plausible."

Timothy was quiet for a moment. Outside, London was doing what it does on a grey Tuesday — carrying on regardless.

"So Claude Code's output in Go looks the same to me whether it's right or wrong."

"Precisely," Margaret said. "That is the core problem of working in a language you don't know. You cannot calibrate confidence. In your own language, you review code and catch things. In an unfamiliar language, you review code and see shapes."

The Three Things You Actually Have

"You are not without resources," Margaret said. "Let me tell you what you actually have."

She picked up her pen.

"First — you have the compiler. Go is a statically typed, compiled language. It will not run code that is structurally wrong. If Claude Code produces something that gets a type wrong, misuses a channel in ways the type system can detect, or makes a structural error — the compiler will tell you." She looked at him carefully. "But I want to be precise about what the compiler does and does not catch. It catches type errors. It catches certain misuses of channels. What it does not catch is a goroutine that is started and never terminates — a leak that compiles cleanly, runs without complaint, and quietly consumes memory until something in production starts behaving strangely under load. The compiler is a safety net for structural errors. It is not a safety net for lifecycle errors. Keep that distinction."

She paused. "Go gives you two more tools that are worth knowing. The first is go vet — a static analyser that catches a class of common mistakes the compiler deliberately ignores, including certain channel misuses and suspicious constructs. Run it as a matter of habit. The second is the race detector — run your tests with go test -race and Go's runtime will instrument your code and flag concurrent access patterns that could produce race conditions. It will not catch every possible race, but it catches many of the common ones, and in a concurrency-heavy codebase you are not yet fluent in, it is an invaluable second pair of eyes."

Timothy wrote both down carefully.

"Run the compiler constantly. Every small addition. Don't accumulate unverified changes — you have no instinct for which ones are safe." She wrote on the notepad. "Second — you have the tests. The platform team has tests for this service, I assume?"

"They do."

"Then you have a specification in executable form. Before you write a line of retry logic, run the existing tests. They should all pass. After every change, run them again. The tests are your early warning system in territory where your own judgment cannot yet be trusted."

"And the third thing?"

"The third thing," Margaret said, "is the most important, and the most commonly skipped." She set down her pen. "Before you write anything, ask Claude Code to teach you the language feature you are about to use. Not to write the code. To explain the concept."

Timothy looked at her.

"For the retry logic — before you touch the worker function, ask: how does error handling work in Go, and what are the common mistakes developers make when implementing retry logic with goroutines? Show me a minimal, executable example. You are not asking for the full solution. You are asking to be taught. A working snippet you can run immediately is worth more than a paragraph of theory — it gives you something to observe, something to break deliberately, something to learn from before you touch the real code." She paused. "Then, when you do ask for the full implementation, you have enough vocabulary to evaluate what you receive."

The Honest Limits

"I want to be honest with you about something," Margaret said. "There are limits to what Claude Code can do for you here, and they are worth knowing."

"Tell me."

"Claude Code can give you correct Go. It can explain patterns, generate idiomatic implementations, catch common mistakes before you make them. For well-documented features of a mature language, it is a reliable guide." She looked at him steadily. "But it cannot give you judgment. And in a language you don't know, judgment is precisely what you are missing."

"What kind of judgment?"

"The kind that says — this implementation is technically correct, but it is not how Go programmers actually write this. The kind that says — this pattern works in a small service but will cause problems at scale. The kind that says — the platform team has conventions I haven't seen yet, and this solution will be rejected in code review not because it is wrong but because it doesn't fit." She paused. "Claude Code does not know your platform team's conventions. It does not know the unwritten rules of the codebase you are entering. It produces good Go. It does not produce their Go."

Timothy was writing quickly.

"There is one more limit," Margaret said. "Concurrency is hard. Not hard in the sense of complex syntax — hard in the sense that the mistakes it produces are subtle, timing-dependent, and sometimes invisible until production. A race condition in a worker pool does not always manifest in tests. It manifests when load increases, when timing shifts, when two goroutines reach the same point at the same moment for the first time." She looked at him. "For concurrency specifically — in a language you don't know — I would ask Claude Code to review the implementation for race conditions explicitly. Not as part of a general review. As a specific, targeted question: are there any race conditions in this implementation, and have I handled channel closure and goroutine lifecycle correctly?"

"Ask about the hard thing directly."

"Always ask about the hard thing directly," Margaret said. "Vague review requests get vague answers. Specific concerns get specific analysis."

The Right Way to Ask

"Show me how you would ask for the retry implementation," Margaret said. "Not the message you would send — the thinking behind it."

Timothy considered. "I need to tell it what the worker function currently does. What retry means in this context — how many attempts, what kind of backoff, what counts as a retriable error versus a permanent failure."

"Good. And on the backoff — be specific about what you need. A simple exponential backoff doubles the wait on each attempt, which is correct as far as it goes. But if you have many workers all failing and retrying simultaneously, they will all back off by the same intervals and hit the downstream service in waves. Production retry logic almost always adds jitter — a small random variation to the backoff interval — so the retries spread out rather than synchronise. Ask Claude Code about jitter explicitly if this service runs at any meaningful scale."

Timothy looked up. "I wouldn't have known to ask that."

"Which is precisely why you ask about the hard thing directly," Margaret said, "and why you tell Claude Code the context — how many workers, what the downstream service is, what the expected load looks like. The right implementation depends on the answers."

"And I should ask it to explain the retry implementation as it writes it — not just give me code, but tell me what each part does and why, so I can actually learn the language while I'm solving the problem."

Margaret set down her pen. "That last part," she said, "is the thing most developers never think to ask. They want the solution. They accept the code, they paste it in, the tests pass, they move on. They have learned nothing about Go. The next time they encounter a goroutine they are in exactly the same position." She looked at him. "You are going to be in Go codebases again. The platform team is not going away. Use this as the first lesson, not a one-time workaround."

He nodded slowly. "Ask it to teach while it solves."

"Ask it to teach while it solves," she said. "That is a different relationship with the tool than most people have. Most people use Claude Code as a vending machine. Put in a problem, receive a solution. You can use it as something closer to a patient tutor who happens to also write the code."

Before He Left

The library had settled into its late afternoon quiet. Somewhere in the stacks, a trolley moved unhurriedly between shelves.

"One more thing," Margaret said. "When you submit this to the platform team for review — tell them you're not a Go developer. Don't hide it."

Timothy looked surprised. "Won't that undermine confidence in the implementation?"

"It will invite the right kind of review," Margaret said. "A reviewer who knows you're unfamiliar with the language will look at the concurrency carefully. A reviewer who assumes you know Go will skim it. You want the careful review. You want someone who knows the codebase to tell you what you got wrong." She paused. "This assumes, of course, that you are working in a team where honesty about what you don't know is treated as professionalism rather than weakness. In a healthy engineering culture, it is. If yours isn't — that is a different problem, and a more serious one." She looked at him steadily. "But pretending to expertise you don't have is how subtle bugs survive code review. It is not a career strategy. It is a liability."

He closed the laptop.

Outside, London had shifted almost imperceptibly toward evening. Inside the library, a developer had just understood something that would stay with him — that working in a language you don't know is not a problem to be hidden. It is a condition to be managed. Honestly, carefully, and with the right help.

Claude Code could give him the Go. Only time and attention would give him the instincts.

And knowing the difference was how you stayed out of trouble until they arrived.

Next episode: Margaret and Timothy explore context — why Claude Code's output changes dramatically depending on what you tell it, and how to build the habit of providing the right information before you ask the question.

If this series is useful to you, share it with a developer who's ever been handed a codebase in a language they've never written.

Aaron Rose is a software engineer and technology writer at tech-reader.blog. For explainer videos and podcasts, check out Tech-Reader YouTube channel.

The Secret Life of Go: Generics

Aaron Rose — Tue, 17 Mar 2026 02:10:57 +0000

Compile-Time Safety, Type Constraints, and When to Write Code Twice

Episode 29

Ethan was staring at a stack trace that had just crashed his local testing environment.

panic: interface conversion: interface {} is string, not main.UserStruct

Eleanor walked by, pausing behind his chair. "A runtime panic. Let me guess: you pulled something out of the sync.Map we built yesterday and tried to cast it to the wrong type."

"I thought I was saving a User struct," Ethan sighed, rubbing his temples. "But somewhere else in the code, I accidentally saved the user's ID as a string under the same key. When I tried to pull it out and assert it as a User, the program blew up."

He leaned back. "You warned me that sync.Map uses any and drops type safety. But this feels like a step backward. Am I really supposed to just cross my fingers and hope I don't typo an interface assertion?"

"Before Go 1.18, yes. You had to rely on strict discipline and unit tests," Eleanor said, taking the seat next to him. "But today, we have a way to get the performance of a concurrent map and the safety of compile-time checks. We use Type Parameters. We use Generics."

The Type Parameter (`[K, V]`)

"Generics allow us to write code that works with multiple types, without sacrificing the compiler's ability to check our work," Eleanor explained. "We are going to wrap the sync.Map in a custom struct."

She opened a new file and typed:

// SafeCache wraps a sync.Map to provide compile-time type safety.
// We define two Type Parameters: K for the key, V for the value.
type SafeCache[K comparable, V any] struct {
    internal sync.Map
}

Ethan pointed at the square brackets. "What is comparable? Why isn't K just any?"

"A map key must be hashable so the map can look it up," Eleanor said. "You can't use a slice or a function as a map key. comparable is a built-in constraint. It tells the compiler: 'Only allow types here that can be compared using == and !='. The value V, however, can be absolutely anything."

The Generic Methods

Eleanor proceeded to write the methods for their new struct.

// Store saves a typed key and value into the internal map.
func (c *SafeCache[K, V]) Store(key K, value V) {
    c.internal.Store(key, value)
}

// Load retrieves a typed value.
func (c *SafeCache[K, V]) Load(key K) (V, bool) {
    val, ok := c.internal.Load(key)
    if !ok {
        var zero V // Create a zero-value of type V to return safely
        return zero, false
    }

    // We can safely type assert to V because Store() guarantees 
    // nothing else could have been saved!
    return val.(V), true 
}

Ethan's eyes lit up. He immediately refactored his calling code:

func main() {
    // We instantiate the generic struct with concrete types
    var userCache SafeCache[string, UserStruct]

    userCache.Store("user_1", UserStruct{Name: "Alice"})

    // ERROR: The compiler stops this immediately! 
    // userCache.Store("user_2", "just a string") 

    // No type assertion needed when loading!
    user, found := userCache.Load("user_1")
    if found {
        fmt.Println(user.Name)
    }
}

"Look at that," Ethan marveled. "I tried to save a string, and my IDE threw a red squiggly line before I even compiled. No more runtime panics. It caught the bug instantly."

"Exactly," Eleanor smiled. "You've hidden the dangerous any interface inside a strictly typed, generic wrapper."

The Architect's Constraint

Empowered by his new tool, Ethan opened up a utility file.

"I have this simple Add function," he said rapidly. "Right now, I have an AddInts(a, b int) and an AddFloats(a, b float64). It's so repetitive. I'm going to use Generics to combine them into one!"

He started typing out constraints, importing golang.org/x/exp/constraints to support mathematical operators.

"Stop," Eleanor said gently but firmly.

Ethan paused.

"Generics are a powerful architectural tool," Eleanor explained. "They are brilliant for data structures—like caches, trees, queues, and linked lists—where the logic of the structure has nothing to do with the data it holds. But they come with a cost. They make your code harder to read, and they increase compile times."

"But I have to write the same three-line function twice," Ethan argued.

"Yes. And you should," Eleanor replied. "There is a famous Go proverb: A little copying is better than a little dependency. Do not use Generics just to save yourself a few keystrokes. If the function is short, write it twice. Embrace the simplicity."

Ethan deleted his generic math function and looked back at his SafeCache. "Use Generics for complex data structures and algorithms. Use copy-paste for simple logic."

"Precisely," Eleanor said, closing her laptop. "Safety where you need it. Simplicity everywhere else."

Key Concepts from Episode 29

Type Parameters ([T any])

Generics use square brackets [] to declare type parameters, allowing functions and structs to operate on abstract types that are defined at instantiation.

Type Constraints

any: An alias for interface{}. Accepts any type.
comparable: A built-in constraint that restricts the type parameter to types that support the == and != operators (required for map keys).

The Generic Wrapper Pattern

A standard Go pattern for providing type safety over standard library tools that rely on any (like sync.Map or sync.Pool). The wrapper handles the dangerous type assertions internally, exposing a strictly typed API to the caller.

The Zero-Value Trick

When returning from a generic function upon failure, you cannot return nil because V might be a value type (like int). Instead, declare var zero V and return zero.

The Architectural Limit

Generics add cognitive load. They should be reserved for data structures (Lists, Sets, generic Caches) and complex algorithms (Sorting, Filtering). They should not be used merely to deduplicate trivial, three-line functions.

Aaron Rose is a software engineer and technology writer at tech-reader.blog. For explainer videos and podcasts, check out Tech-Reader YouTube channel.

The Secret Life of Claude Code: Reading Code You Didn't Write

Aaron Rose — Sun, 15 Mar 2026 23:12:17 +0000

How to orient yourself in an unfamiliar codebase — and how Claude Code can help you find your footing without losing your judgment

Margaret is a senior software engineer. Timothy is her junior colleague. They work in a grand Victorian library in London — the kind of place where inherited collections are treated with respect, and where no one pretends to have read something they haven't. Timothy has arrived today with someone else's problem.

Episode 6

The Inheritance

He set the printed file listing on the table without saying anything. Margaret looked at it the way she sometimes looked at things — unhurried, reading from the top.

It was long.

"Whose is it?" she said.

"It was Marcus's. He left in February. It's a billing integration — handles subscription renewals, proration calculations, payment retries, webhook processing." He paused. "There's no documentation. There are comments, but most of them describe what the code does, not why it does it."

"And you need to do what with it?"

"Add support for a new payment provider. The product team wants it by end of month."

Margaret was still looking at the file listing. "How long have you been staring at it?"

"Since Monday."

"And today is Thursday."

"Yes."

She set the paper down. "Tell me what you've understood so far."

"The entry point is clear. The webhook handler is clear. But somewhere in the middle there's a proration engine that I genuinely cannot follow. The variable names are... interpretive. There are functions that call other functions that seem to call back into the first ones." He looked at her. "I don't know where to start."

"You started in the wrong place," Margaret said. "That is what we are going to talk about today."

Why Unfamiliar Code Resists Reading

"Most developers," Margaret said, "approach unfamiliar code the way they approach a novel someone has left open to page 200. They try to understand the page they're on. They get confused because they lack context. They flip back a few pages, get more confused, and conclude that the code is badly written."

"It might be badly written."

"It might be," she allowed. "But that conclusion comes later. First you need to read it properly." She picked up her pen. "There are two fundamental mistakes people make with unfamiliar code. The first is starting in the middle. The second is trying to understand everything before understanding anything."

Timothy looked at the file listing. "I did both."

"Most people do. The proration engine that's confusing you — do you know yet whether it's actually complex, or whether it only feels complex because you don't know what it's supposed to do?"

He was quiet for a moment. "I don't know."

"That is the correct answer," Margaret said. "And it tells you something important. You cannot evaluate code you don't yet have a model for. Before you try to read the proration logic, you need to understand what proration is doing in the context of this system. Not the code. The behaviour."

The Two Passes

"Before you open the code," Margaret said, "you make two passes. Most developers skip both of them and pay for it."

She turned the notepad toward him.

"The first pass is the map pass. You are not reading code. You are reading structure. File names. Directory organisation. The top-level shape of things. Function names — not their bodies, just their names. What does this codebase think is important? What are its concepts? What are the things it has chosen to name?"

"I did look at the file names."

"Did you write them down?"

He hadn't.

"Write them down," Margaret said. "Build a vocabulary. If you see prorateCharges, applyCredit, calculateMidCycleDelta — those are concepts. Before you read a single line of implementation, you should be able to describe the system in its own language." She paused. "This is where Claude Code becomes genuinely useful. Not to read the code for you. To help you build the map."

"How?"

"You paste in the structure. The file names, the function signatures, the class names. You say: based on these names and the organisation of this codebase, describe what you think this system does, what its main concepts are, and what questions you would want to answer before adding a feature to it. What you get back is not a definitive answer. It is a hypothesis — a starting model that you will test and refine as you read."

Timothy wrote this down carefully.

"The second pass is the flow pass. You pick one complete path through the system — one transaction, one webhook event, one renewal — and you follow it from entry to exit. Not everything. One thing. You are tracing a thread, not reading a book."

"And Claude Code?"

"The same way. Paste in the relevant files, describe the path you are trying to follow, and ask: what is this code doing along this path, and where does the path go? Again — a hypothesis. You are building a model, not receiving a verdict."

The Hypothesis Model

"I want to be precise about something," Margaret said. "When you use Claude Code to read unfamiliar code, it is giving you a hypothesis, not a fact. It reads what is there. It does not know why decisions were made. It does not know what requirements existed that no longer exist. It does not know what the comment above the function originally said before someone updated the code without updating the comment."

"It reads the code as it is."

"Exactly. Which is more than you have right now, but less than the full picture." She looked at him steadily. "This is the discipline. You take what Claude Code gives you, and you treat it as a starting point for questions, not as answers. If it says this function calculates proration by comparing the days remaining in the billing cycle to the total days, your response should not be great, I understand proration now. Your response should be: is that the right way to calculate proration for this product's billing model, and does the code actually do that consistently?"

"Test it against the actual code. Run it with real inputs. Find the edge cases the reading doesn't reveal. Claude Code can help you generate those tests — given this proration logic, what inputs would expose incorrect behaviour? But you are the one who decides whether the tests are asking the right questions."

What to Do With the Middle

"The middle," Timothy said. "The part I can't follow. What do I do with that specifically?"

"The middle is always the hardest part," Margaret said, "because by the time you get there, the code assumes you have context you don't have. You are missing the vocabulary of decisions — why things were done the way they were done." She set down her pen. "There are three things you can do."

"First — trace from the known. You said the webhook handler is clear to you. Start there. What does the webhook handler call? Follow that one call. Not where it leads eventually — just the immediate next step. Build the understanding one function at a time from a place of stability."

Timothy was nodding slowly. He had been trying to understand the middle in isolation.

"Second — read the tests. If there are tests — and Marcus, to his credit, wrote tests — they are documentation. They describe behaviour from the outside. A test that says when a subscription upgrades mid-cycle, the prorated charge should equal the per-day difference times the remaining days tells you more about the intention than the implementation does."

"Marcus did write tests," Timothy said. "I glanced at them."

"Don't glance at them. Read them. They are the clearest statement of what the code was meant to do." She allowed a brief pause. "And when you take those tests to Claude Code — not the implementation, the tests — and ask: what behaviour do these tests define, and are there cases they don't cover? — you get something valuable. You get an independent read of the specification."

"And the third thing?"

"Accept that some parts of the middle will not be clear until you have changed something." She looked at him. "There is a limit to understanding from reading. At some point you have to make a small, reversible change in a local environment with the test suite running, watch what breaks, and let the breakage teach you what the reading couldn't. This is not guessing. It is disciplined experimentation — but only ever against a test harness, never against code whose effects you cannot roll back. In a billing system especially, the cost of an uncontrolled experiment is not a failed build. It is a customer's incorrect charge."

He wrote that down without being asked.

"You form a hypothesis — this function is responsible for x — you make a change that would expose whether that hypothesis is correct, and you observe the result. The test suite is your safety net. Do not experiment without it."

The Question of Trust

"How much do I trust the code?" Timothy asked. It was the question that had been sitting under everything else.

Margaret considered it. "You trust it the way you trust a map of a city you've never visited. It is likely to be mostly accurate. It may be out of date in places. There may be roads that exist that aren't on the map, and roads on the map that no longer exist. You use it to navigate, but you look up from it."

"And Claude Code's reading of the code?"

"The same. More useful than nothing. Less authoritative than understanding you've built yourself." She picked up her tea. "Here is what I would say to you about trust, specifically. The code that is easy to follow — trust it provisionally and verify the edge cases. The code that is hard to follow — do not trust it at all until you understand why it's hard to follow."

She set the cup down carefully.

"Hard to follow code is sometimes cleverness — a developer who knew the language very well and optimised for terseness. It is sometimes the accumulated residue of decisions that made sense at the time, layered over years until the original shape is no longer visible. It is occasionally a genuine mistake that no one caught because no one wanted to look at it too closely." She paused. "And in billing systems specifically, it is sometimes none of those things. It is compliance. Tax law varies by jurisdiction. Payment processors impose constraints that have no business logic explanation. PCI requirements leave fingerprints in code that look arbitrary until you know what they're protecting against. Before you decide that something strange is a mistake and should be refactored — find out whether it was strange for a reason."

"How do I find that out?"

"The commit history," Margaret said. "Which brings me to something I should have said earlier."

Before He Left

Outside, a London afternoon was doing what London afternoons often do — persisting with determined neutrality, neither quite grey nor quite clear.

"You said I started in the wrong place," Timothy said. "Where should I have started?"

"At the beginning," Margaret said. "Not the beginning of the file. The beginning of your understanding." She looked at him. "You should have spent the first day not reading the code at all. Reading what the system does. The product documentation, if there is any. Then the commit history — not just the messages, but the pattern of them. Which files change together. Which functions have been touched repeatedly. A file that has been modified fifteen times in two years is trying to tell you something. A function whose commit message says hotfix: edge case for annual subscribers in EU is carrying context that the code itself cannot."

"I didn't look at any of that."

"Pull requests are the same. When Marcus opened a PR for a change to the proration engine, the conversation in that PR — the questions the reviewers asked, the justifications Marcus gave, the back-and-forth before it was merged — that is the documentation that never made it into the comments. Most developers never read it. It is the closest thing to sitting next to the person who wrote the code."

"That's all there, in the repository."

"All of it," Margaret said. "And Claude Code can help you make sense of it — paste in a commit thread or a PR description and ask: what problem was this change trying to solve, and what assumptions does it make? The history is a record of decisions. Decisions have reasons. The reasons are what you need."

He gathered his things slowly, the way he did when he was still processing something.

"One more thing," Margaret said. "When you do understand it — when you've built the model and tested it and you feel confident — write it down. Not for Marcus, and not for yourself. For the person who inherits this code from you."

She looked at him steadily.

"Because they will be standing exactly where you are standing now. And they will deserve better than three days of confusion before they find their footing."

He closed his notebook.

Outside, the London afternoon persisted. Inside the library, a developer had just learned that reading code you didn't write is less about cleverness than about patience — and that the map you build before you start walking is the thing that makes the rest of the journey possible.

Next episode: Margaret and Timothy turn to the language you don't know — how to approach a codebase written in an unfamiliar language, and what Claude Code can and cannot do when you're outside your expertise.

The Secret Life of Claude Code publishes on tech-reader.blog every other day.

If this series is useful to you, share it with a developer who needs to inherit someone else's code.

Aaron Rose is a software engineer and technology writer at tech-reader.blog. For explainer videos and podcasts, check out Tech-Reader YouTube channel.

Happy Pi Day!

Aaron Rose — Fri, 13 Mar 2026 01:38:17 +0000

3.14159265358979323846264338327950288419716939937510...

The Secret Life of Claude Code: The Art of the Follow-Up

Aaron Rose — Wed, 11 Mar 2026 01:29:07 +0000

What to do when Claude Code gets it almost right — and how one disciplined follow-up gets you the rest of the way there

Margaret is a senior software engineer. Timothy is her junior colleague. They work in a grand Victorian library in London — the kind of place where conversations are finished properly, and where almost right is understood to be a different thing entirely from right. Timothy has arrived today with something he is not sure what to do with.

The Almost

He sat down without his usual preamble and turned the laptop toward her immediately. This, Margaret had learned, meant he wanted her to look before he explained. He was uncertain about something and did not yet have the words for it.

She looked.

On the screen was a function — a data export utility, clean and reasonably structured. She read it the way she always read code: slowly, without expression, beginning to end.

"Claude Code?" she said.

"Yes. Second attempt, actually. The first one was completely off. This one is..." He paused. "Close."

"Close," she repeated.

"It handles the main cases. The CSV export works. The date formatting is correct. But it doesn't handle empty datasets — it just throws an error instead of returning an empty file. And the column headers are hardcoded when they should come from the data schema."

Margaret looked at the code again. "And what did you do when you noticed this?"

Timothy hesitated. "I'm not sure whether to fix it myself, start over with a new prompt, or..." He trailed off.

"Or what?"

"Or tell Claude Code what's wrong and ask it to fix it."

Margaret set the laptop down between them. "That third option," she said. "That is what we are going to talk about today."

Why Developers Don't Follow Up

"Most developers," Margaret said, "when they receive output that is almost right, do one of three things. They accept it and patch it manually. They discard it and start over from the beginning. Or they send a vague correction and hope for the better."

"I've done all three," Timothy admitted.

"Most people have. None of them are wrong exactly — but none of them are the most effective approach either." She picked up her pen. "Patching manually makes sense for a trivial fix. Starting over makes sense if the output is fundamentally misconceived. But when the output is close — when the structure is sound and only specific behaviours are wrong — there is a better path."

"The follow-up."

"The follow-up," she confirmed. "Which is not simply sending another message. It is a skill. And like the first prompt, it requires thinking before typing."

What a Follow-Up Actually Is

"Think about what Claude Code knows at this point," Margaret said. "It has your original prompt. It has the solution it produced. It has no idea what you think of that solution — what worked, what didn't, what you expected that you didn't get."

"So I need to tell it."

"Precisely. But how you tell it matters enormously." She turned the notepad toward him. "A poor follow-up says: this doesn't work, try again. It gives no information. Claude Code will produce another attempt — possibly better, possibly worse, almost certainly not targeted at the actual problem."

Timothy was already nodding. He had sent that message before, in different words.

"A good follow-up," Margaret continued, "does three things. It acknowledges what worked. It identifies precisely what didn't. And it adds any context that was missing from the original prompt — because if the first output was wrong in a specific way, that wrongness often reveals a gap in what you originally provided."

She wrote three short phrases on the notepad:

What worked.
What didn't, and exactly how.
What I should have told you the first time.

"That third one," Timothy said. "That's the one people skip."

"Always," Margaret said. "Because it requires admitting that the original prompt was incomplete. Which it almost always is. The first output is not just a solution — it is a diagnostic. It shows you what Claude Code understood from what you gave it. When the output is wrong in a particular way, that wrongness is information about your prompt."

The Diagnostic Read

"Show me the error," Margaret said. "When the empty dataset is passed."

Timothy pulled up the output. The function threw a TypeError — it attempted to access the first row of the data to infer column structure, and when there was no first row, it failed.

"What does that tell you?" Margaret asked.

"That it assumed there would always be data."

"Yes. And why did it assume that?"

Timothy thought for a moment. "Because I didn't mention empty datasets in the prompt."

"Correct. The error is not a failure of Claude Code's ability. It is a reflection of your prompt's silence on edge cases." She looked at him steadily. "This is the diagnostic read. Before you write your follow-up, you ask: what did this output assume that I never specified? The answer to that question tells you exactly what to add."

He turned back to the laptop. "The column headers being hardcoded — that's the same thing. I said 'export to CSV' but I never said the headers should be dynamic."

"You assumed it would infer that from context. It did not." She allowed a small pause. "This is not a criticism of your original prompt. It is almost impossible to specify everything in advance. The follow-up exists precisely because the first exchange is a dialogue, not a transaction."

The Follow-Up Prompt

"Now write it," Margaret said. "The follow-up. Not yet — think first."

Timothy was quiet for a moment. Outside, London was doing what London does in the early evening — settling into itself, lights coming on in the buildings across the way.

"I need to acknowledge that the main export logic is correct," he said slowly. "So it doesn't throw that away and start over."

"Good."

"Then I need to describe the two specific problems. Not just name them — describe them. The empty dataset case should return an empty CSV with headers but no rows. The column headers should be derived from the schema object, not hardcoded."

"Better. And the third part?"

He thought. "I should tell it about the schema object. I don't think I mentioned it in the original prompt at all."

"You did not."

"So Claude Code invented the hardcoded headers because it had no idea the schema existed." He sat back. "The bug was in my prompt."

"The gap was in your prompt," Margaret said, not unkindly. "There is a difference. A bug implies carelessness. A gap implies incompleteness. The first prompt is rarely complete. That is why the follow-up exists."

Timothy wrote the follow-up carefully. He began by saying that the core export logic was working correctly and should be preserved. He then described each problem specifically — what was happening, what should happen instead, and under what conditions. Finally, he introduced the schema object he had omitted, describing its structure and how the headers should be derived from it.

He read it back aloud — the habit Margaret had taught him — and caught one imprecision. He corrected it before sending.

The response came back targeted and specific. The core logic was untouched. The empty dataset case now returned a header row with no data rows. The column headers were drawn cleanly from the schema.

"It didn't start over," Timothy said.

"Because you told it not to," Margaret said. "By describing what worked, you gave it permission to build on what already existed rather than replace it. That is not a small thing. A follow-up that begins with what is wrong invites a complete rewrite. A follow-up that begins with what is right invites a precise correction."

The Conversation, Not the Transaction

"I've been thinking of each prompt as a separate request," Timothy said. "Like placing an order."

"Most people do," Margaret said. "But that is not what it is. Claude Code holds the context of your conversation. It knows what you asked, what it produced, what you said in response. You are not placing a series of independent orders — you are having a conversation with a very capable colleague who happens to have no memory beyond the current session."

"So the follow-up is just... the next thing I would say in a conversation."

"Exactly that. If a colleague had built you this function and you found two problems with it, you would not hand it back and say this is wrong, do it again. You would say — the main logic is good, there are two things to address, and I should have mentioned this third thing earlier. That is a professional exchange. That is what a good follow-up sounds like."

Timothy looked at the corrected function on the screen. Clean, complete, handling every case he needed.

"How many follow-ups is too many?" he asked.

"That depends on what each one achieves," Margaret said. "If each follow-up produces meaningful progress toward the right answer, continue. If you find yourself sending the same correction and receiving the same gap in return — that is the signal to step back. Not to abandon the conversation, but to reconsider whether the context you have provided is sufficient." She paused. "Sometimes the right move is to start fresh with a prompt that incorporates everything you have learned from the previous exchange. The conversation was not wasted. It taught you what the prompt needed to contain."

Before He Left

The library was quieter now. The afternoon had become evening without either of them particularly noticing.

"There is one more thing," Margaret said. "When Claude Code produces something that is almost right — resist the urge to feel that almost right is good enough. It is not impatience or perfectionism to want the right answer. It is professional standards."

"I nearly accepted the hardcoded headers," Timothy said. "I thought — close enough, I can deal with it later."

"Later has a way of becoming never," Margaret said. "And a function with hardcoded headers will cause someone a problem at some point — possibly you, possibly someone who inherits your code, possibly a user. The follow-up costs five minutes. The fix costs considerably more when it arrives at the wrong time."

She picked up her tea.

"Claude Code is a patient correspondent. It does not tire of the conversation. It does not take corrections personally. It does not resent being asked to do better. Use that. The follow-up is not an admission that the first attempt failed — it is the natural continuation of a dialogue that was always going to take more than one exchange to get right."

He closed the laptop.

Outside, the lights of London had come fully on. Inside the library, a developer had just understood something that would change how he worked every day — that the first response is not the destination. It is the beginning of the conversation.

And knowing how to continue that conversation is a skill worth building.

Next episode: Margaret and Timothy turn to a different kind of challenge — reading code you didn't write. How to orient yourself in an unfamiliar codebase, and how Claude Code can help you find your footing without losing your judgment.

The Secret Life of Claude Code publishes every other day.
If this series is useful to you, share it with a developer who needs to hear it.

Aaron Rose is a software engineer and technology writer at tech-reader.blog. For explainer videos and podcasts, check out Tech-Reader YouTube channel.

The Secret Life of JavaScript: The Observer

Aaron Rose — Tue, 10 Mar 2026 04:45:48 +0000

Stop Polling the DOM: Mastering the Intersection Observer API

Timothy leaned back in his chair, listening to the sudden, aggressive whir of his laptop fan. He had just finished implementing a lazy-loading feature for a massive grid of user profile pictures.

"The scroll is perfectly smooth," Timothy said, tapping his screen. "I used the { passive: true } flag we talked about yesterday. The Compositor Thread is completely unblocked. But my CPU usage just spiked to ninety percent, and my laptop sounds like it is preparing for takeoff."

Margaret strolled over, her dark roast coffee in hand, and peered at the performance monitor on his secondary display.

"You successfully unblocked the train," Margaret said, nodding at the screen. "But you are torturing the dispatcher."

She pointed to the block of code responsible for the lazy loading.

const images = document.querySelectorAll('img[data-src]');

window.addEventListener('scroll', () => {
  images.forEach(img => {
    // Calculate exact geometry on every scroll tick
    const rect = img.getBoundingClientRect();

    // If the image enters the viewport, load it
    if (rect.top < window.innerHeight) {
      img.src = img.dataset.src;
    }
  });
}, { passive: true });

"You remembered our lesson on Layout Thrashing," Margaret explained. "Every time you call getBoundingClientRect(), you force the browser to calculate the exact, pixel-perfect geometry of the DOM. Doing that is expensive."

Timothy defended his code. "But I have to know where the images are so I can load them before the user sees blank spaces."

"Yes, but look at when you are asking," Margaret said. "You tied that heavy mathematical calculation to the scroll event. Even though it is a passive listener, that event fires dozens of times a second. You are forcing the Main Thread to frantically calculate the exact GPS coordinates of every single passenger, every time the train moves an inch. You are essentially sitting in the backseat of a car, poking the driver fifty times a second, screaming, 'Are we there yet? Are we there yet?'"

"So how do I know when the image enters the screen without asking?" Timothy asked.

"You stop polling, and you set a tripwire," Margaret smiled. She introduced a new concept to the whiteboard. "You use the IntersectionObserver API."

"An Observer flips the entire architecture," Margaret continued. "Instead of using JavaScript to constantly ask the browser for geometric coordinates, you hand a list of elements over to the browser's highly optimized, internal C++ engine. The browser engine natively understands the viewport. It handles all the spatial mathematics quietly in the background. The Main Thread goes completely to sleep, and the browser simply taps your JavaScript on the shoulder exactly when an element crosses the threshold."

"And you can configure exactly where that tripwire sits," she added. "By setting a rootMargin of, say, 100px, you tell the browser to tap your shoulder just before the image enters the screen, completely eliminating that split-second white flash. You can even use the threshold option to wait until exactly 50% or 100% of the element is visible."

Timothy deleted his scroll listener and his getBoundingClientRect() loop entirely. He created an options object and instantiated a new IntersectionObserver.

const images = document.querySelectorAll('img[data-src]');

const options = {
  rootMargin: '100px', // The tripwire: fire 100px before entering the viewport
  threshold: 0         // Fire as soon as 1 pixel crosses the line
};

// 1. Create the tripwire
const observer = new IntersectionObserver((entries, observer) => {
  entries.forEach(entry => {
    // 2. The browser taps JavaScript on the shoulder
    if (entry.isIntersecting) {
      const img = entry.target;
      img.src = img.dataset.src; // Load the image

      // 3. Stop watching this specific image once it loads
      observer.unobserve(img); 
    }
  });
}, options);

// 4. Register all images with the internal C++ engine
images.forEach(img => observer.observe(img));

"Look at the elegance of that," Margaret said, watching him save the file. "There is zero math on the Main Thread. Modern frameworks like React actually wrap this entire C++ engine interaction into simple hooks like useInView(), giving you this performance benefit with even less code. But underneath, the architecture is exactly what you just wrote: The JavaScript only wakes up when an image actually triggers the tripwire, it does exactly one job, and then it immediately unobserves the element so it never fires again."

Timothy refreshed the page and began scrolling furiously down the massive grid of profiles.

The scrolling remained buttery smooth. The images popped into existence perfectly just before they crossed into view. The dispatcher was no longer being poked constantly; he was waiting patiently, and the browser itself was sending a signal only when a passenger actually needed to get off.

Best of all, the frantic whirring of his laptop fan slowly spun down into complete silence.

Aaron Rose is a software engineer and technology writer at tech-reader.blog. For explainer videos and podcasts, check out Tech-Reader YouTube channel.

The Secret Life of Claude Code: When Claude Code Gets It Wrong

Aaron Rose — Mon, 09 Mar 2026 01:05:16 +0000

Three ways Claude Code gets it wrong — and the discipline that catches all of them before they ship

Margaret is a senior software engineer. Timothy is her junior colleague. They work in a grand Victorian library in London — the kind of place where precision matters and confidence is not the same thing as correctness. Timothy has arrived today in unusually good spirits. This, Margaret has learned, is sometimes cause for concern.

What Timothy Was Proud Of

He came through the door with the particular energy of someone who had solved something.

"I fixed it," he said, settling into his chair with the satisfaction of a man who had earned his tea. "The user authentication bug. The one that's been sitting in the backlog for two weeks."

"Tell me," Margaret said.

"I described the problem to Claude Code — properly this time, the way we talked about. Context, specific behaviour, constraints. It gave me a solution, I reviewed it, it looked right, I tested it, it passed. Deployed this morning."

"And it worked?"

"Perfectly. Users can log in, sessions are handled correctly, no errors in the logs." He opened his laptop. "I wanted to show you the code."

Margaret looked at it. She read slowly, as she always did — not skimming, not nodding along, but actually reading. Timothy had learned not to fill this silence.

After a moment she said, "Walk me through the session expiry logic."

"It resets the session token on each login. Clears the old one, generates a new one, stores it with a timestamp."

"And when does the session expire?"

"Twenty-four hours after the timestamp."

"After which timestamp?"

Timothy looked at the screen. Then he looked at it more carefully.

"After the..." He stopped.

Margaret waited.

"After the creation timestamp," he said slowly. "Not the last activity timestamp."

"No."

The good spirits left the room quietly, the way warmth does when a window is opened in winter.

"So a user who logs in and stays active," Timothy said, "will still be logged out after twenty-four hours regardless."

"Yes."

"Even if they were active thirty seconds ago."

"Yes."

He sat back. "That's going to be a terrible experience."

"It is going to be a very frustrating experience," Margaret agreed, "for any user who is in the middle of something when the clock runs out." She looked at him steadily. "The code is not broken, Timothy. It does exactly what it was written to do. It simply does not do what you needed it to do."

The Shape of the Problem

He stared at the screen for a moment. "But I tested it."

"What did you test?"

"I logged in. The session worked. I logged out, logged back in. New token, no errors."

"Did you test a session that had been active for twenty-three hours and fifty-nine minutes?"

"No," he admitted. "Obviously not."

"Did you test what happens to an active user when their session expires mid-task?"

"No."

"Did you consider that the requirement might be sliding expiry — resetting the clock on activity — rather than fixed expiry from login?"

A pause. "I didn't think about it in those terms."

"Claude Code did not think about it in those terms either," Margaret said. "Because you did not ask it to. You described a bug — sessions not being cleared correctly — and it fixed that bug. Cleanly and correctly. But the behaviour you actually needed was never specified, so it was never built."

She picked up her pen.

"This is the shape of the problem. Claude Code gave you a confident, well-structured, functional solution to the problem you described. It was not the solution to the problem you had."

Confidence Is Not a Signal

"That's what bothers me most," Timothy said. "The code looked right. It read like something I would have written on a good day — clean, commented, sensible variable names. There was nothing in it that said this might not be what you need."

"There never is," Margaret said. "This is the important thing to understand. Claude Code cannot reliably flag gaps in your requirements. When something is ambiguous or unspecified, it does not stop and ask — it fills the gap with a reasonable assumption and continues. It will tell you if a function does not exist, or if a pattern is deprecated, or if there is a type mismatch. But it cannot tell you if the behaviour it has implemented matches the behaviour your users actually need. That knowledge lives only in your head. And in the heads of your users."

"So the confidence of the output is meaningless."

"The confidence of the output is a measure of technical coherence," Margaret said carefully. "The code is consistent. The logic follows. The syntax is correct. Those things Claude Code can assess, and it is very good at them. But correctness in the deeper sense — does this do what the business needs, does this serve the user well, does this handle the edge cases that matter — that is yours to verify. Always."

Timothy looked at the code again with different eyes. It had not changed. But he had.

"It's like getting directions to the wrong address," he said. "Delivered with complete confidence."

"That is an excellent description," Margaret said. "And the directions may be perfect. Every turn correct. Arrive precisely where you were told to go. The question is whether that was where you needed to be."

The Three Failure Modes

She drew three short lines on her notepad, the way she sometimes did when organising a thought.

"When Claude Code gets it wrong," she said, "it tends to do so in one of three ways. It is worth knowing all three."

First — *the wrong problem.* This is what happened today. You described a problem, Claude Code solved that problem, but the problem you described was not the whole problem. The output is technically correct and functionally incomplete. This is the most common failure mode, and the most insidious, because the code works. It just does not work enough.

Timothy was writing.

Second — *the outdated answer.* Claude Code's knowledge has a boundary in time. For well-established patterns it is reliable. But for libraries that move quickly, for APIs that change, for security practices that have evolved — it may give you an answer that was correct some time ago and is subtly wrong today. A hashing algorithm that was once acceptable. An authentication library that has since been superseded. A configuration pattern that newer versions have deprecated. The code will look reasonable. It will often run. And it will carry a flaw you did not know to look for. Always check the version. Always verify against current documentation for anything where recency matters.

"And third?"

Third — *the plausible fabrication.* Occasionally — not often, but occasionally — Claude Code will produce something that looks authoritative but is simply invented. A function that does not exist. A parameter that was never part of the API. A configuration option that sounds reasonable but cannot be found in any documentation. It will not announce this. It will present the fabrication with the same tone as everything else.

Timothy looked up. "How do you catch that one?"

"You run the code," Margaret said. "And you read the error message carefully. A plausible fabrication almost always fails at runtime, because the thing it invented does not exist in the actual system. The code looks right. Then it breaks in a very specific way — a missing attribute, an unknown method, a module that cannot be found." She looked at him. "When you see an error that suggests something simply does not exist — resist the urge to assume you have made a mistake. Consider that the solution may have invented something."

What Review Actually Means

"I did review the code," Timothy said. There was a defensiveness in it — not hostile, but genuine. He wanted to understand where he had gone wrong.

"I know you did," Margaret said, without any edge. "And the review was not useless. You would have caught a syntax error, a missing import, an obvious logic flaw. Code review has real value." She paused. "But there is a difference between reviewing code for technical correctness and reviewing code for behavioural completeness. Most developers only do the first. It is what we were trained to do — read the code, understand the code, verify the code does what it appears to do."

"But not whether it does what it should do."

"Exactly. That second question requires you to step outside the code entirely and ask: what are the real requirements here? Not what did I ask Claude Code to build. What does this feature actually need to do for a real user in a real situation?" She set down her pen. "Write those requirements down before you look at the solution. Even briefly. Even just three or four bullet points. Then compare what you wrote to what was built."

"I didn't write any requirements."

"No. You had them in your head — loosely — and you assumed the output would match them. This is a very human thing to do. We are pattern-matchers. The code looked like the right shape, so we accepted it as the right answer."

Timothy was quiet for a moment. Outside, the sounds of the city continued without interest in the conversation.

"If I had written down that sessions should expire on inactivity," he said, "I would have caught it immediately."

"Before you sent the prompt," Margaret said. "And the prompt itself would have been better — because it would have contained the actual requirement." She allowed a small pause. "The preparation we discussed last time protects you here as well. A precise prompt is harder to misanswer. A vague prompt can be answered correctly in ways that do not help you at all."

Before He Closed the Laptop

"I need to fix this today," Timothy said.

"You do," Margaret agreed. "It is a minor fix — update the expiry logic to track last activity rather than creation time. Claude Code will handle it well if you describe the requirement precisely."

"And this time I know what the requirement actually is."

"Yes. That is the difference." She looked at him. "Do not be discouraged by this, Timothy. What happened today is not a failure of your abilities. It is a failure of a habit you have not yet built — the habit of separating what you asked for from what you needed. That habit takes time. You are building it now."

He nodded slowly. "The code was good. The requirement was incomplete."

"And that distinction matters enormously," Margaret said. "Because it tells you where to look. Not at the tool. At the thinking before the tool."

She picked up her tea.

"Claude Code did not deceive you. It answered the question you asked. The discipline — and it is a discipline — is learning to ask questions complete enough that the answer cannot mislead you, even when it is technically correct."

He closed the laptop.

Outside, London was carrying on in its unhurried way. Inside the library, a developer had just learned something that could not be learned from documentation — the difference between code that works and code that is right.

They are not always the same thing.

And knowing that is half the work.

Next episode: Margaret and Timothy explore the art of the follow-up — what to do after Claude Code gives you something that is almost right, and how to guide the conversation toward what you actually need.

If this series is useful to you, share it with a developer who needs to hear it.

Aaron Rose is a software engineer and technology writer at tech-reader.blog. For explainer videos and podcasts, check out Tech-Reader YouTube channel.

The Secret Life of JavaScript: The Scroll

Aaron Rose — Sun, 08 Mar 2026 19:16:33 +0000

Unblocking the Compositor: How to Fix Mobile Scroll Lag

Frozen

Timothy swiped his thumb across his Android screen. The parallax dashboard he had spent all morning building lurched forward, froze for a fraction of a second, and then snapped to a new position. It felt like dragging a brick through mud. He dropped the phone on his desk and glared at his desktop monitor, where the exact same code was running flawlessly in his dark-themed IDE.

"I don't understand," Timothy muttered. "I batched my DOM reads and writes. I used requestAnimationFrame. The Main Thread is completely optimized, but the mobile experience is completely unusable."

Margaret leaned against his cubicle wall, her signature dark roast coffee in hand. She picked up his phone, swiped the screen, and watched the UI stutter.

"Your Main Thread might be optimized, but you are still forcing the browser to use it for something it shouldn't," Margaret said. She set the phone down and pointed to a single line of code on his screen.

window.addEventListener('scroll', () => {
  // Complex parallax math and DOM updates
  updateParallaxPositions();
});

The Compositor Thread

"Scrolling is so fundamental to the web experience that modern browsers created a dedicated, hardware-accelerated lane just for it," Margaret explained. "It is called the Compositor Thread. It runs directly on the GPU, completely separate from the Main Thread where your JavaScript lives. When a user swipes their screen, the Compositor Thread wants to instantly slide the page up or down at a perfect sixty frames per second."

Timothy frowned. "If it has its own dedicated thread, why is my scroll lagging?"

"Because you attached a standard event listener to the window," Margaret said. "And this is especially critical for touchstart and touchmove events on mobile devices, where every millisecond of delay ruins the feel of the app. By listening to those events, you forced the lightning-fast Compositor Thread to hit the brakes. Before the browser can move the page even a single pixel, the Compositor has to pause, look over at the Main Thread, and ask, 'Hey, did Timothy write event.preventDefault() in his JavaScript? Is he trying to cancel this scroll?'"

A High-Speed Train

She grabbed a marker and drew a quick diagram on the whiteboard. It showed a high-speed train representing the Compositor Thread, forced to stop at a railroad crossing every few feet to ask a busy dispatcher for permission to proceed.

Without passive:  🚂---🚦---🚂---🚦 (Waiting for Main Thread)
With passive:     🚂🚂🚂🚂🚂🚂🚂🚂 (Clear track on GPU)

"The browser engine is incredibly cautious," Margaret continued, pointing to the stoplights. "It assumes that because you are listening to the event, you might want to intercept and cancel it. So, it waits for your JavaScript to execute on every single pixel of movement. If the Main Thread is busy fetching data or parsing a script, the Compositor Thread just sits there, waiting at the red light. That waiting is the stutter you feel on your phone."

Timothy looked at his code. "But I am not canceling the scroll. I just want to know where the scroll position is so I can update my parallax elements. How do I tell the browser to stop waiting for me?"

A Contract With the Browser

"You sign a contract," Margaret smiled. "You give the browser a legally binding promise that you will not call event.preventDefault(). You do this by passing a configuration object to your event listener."

Timothy updated his code, adding the third argument to the event listener.

window.addEventListener('scroll', () => {
  // Complex parallax math and DOM updates
  updateParallaxPositions();
}, { passive: true });

"Modern browsers actually default scroll, touchstart, and wheel events to passive: true to try and save developers from themselves," Margaret noted. "But explicitly setting it guarantees the behavior across all environments and proves you actually understand the architecture underneath your code."

"That single flag changes the entire dynamic. You just told the browser engine, 'I am watching the scroll, but I promise I will not interfere with it.' Instantly, the Compositor Thread is untethered. It handles the scrolling on the GPU without ever waiting for the Main Thread, and your JavaScript simply receives the updates asynchronously."

"And if I actually need to stop the scroll?" Timothy asked.

"Then you cannot use the flag," Margaret replied. "If you are building a custom swipe carousel or a sliding drawer where you do need to call preventDefault() to stop the native scrolling, you have to use an active listener. The contract requires absolute honesty."

Running Fast

Timothy saved the file and picked up his Android phone. He placed his thumb on the glass and swiped.

The dashboard flew up the screen. The parallax elements drifted perfectly in the background. There was no hesitation, no stutter, and no lag. The high-speed train was finally running on a clear track.

Aaron Rose is a software engineer and technology writer at tech-reader.blog. For explainer videos and podcasts, check out Tech-Reader YouTube channel.

The Secret Life of Claude Code: The First Prompt

Aaron Rose — Sat, 07 Mar 2026 01:52:11 +0000

Why the quality of your prompt is really the quality of your thinking

Margaret is a senior software engineer. Timothy is her junior colleague. They work in a grand Victorian library in London — the kind of place where precision is valued and vagueness is gently corrected. Timothy has arrived with a real problem and a prompt he is rather proud of.

Episode 3: The Craft of the First Prompt

What Timothy Brought In

He arrived with his laptop already open, which Margaret took as a good sign. It meant he had been thinking before he walked through the door.

"I have a real one today," he said, settling into his chair. "Not a toy example. An actual problem from the codebase."

"Good," Margaret said. "Show me what you've written."

He turned the laptop toward her. On the screen was a prompt he had prepared:

"Fix the performance issue in my data processing pipeline."

Margaret read it. Then she looked at him over her glasses with the particular expression she reserved for moments that required patience.

"Timothy," she said. "What is wrong with this prompt?"

He shifted slightly. "I thought it was fairly clear."

"It is not clear at all," she said, not unkindly. "It is the prompt of someone who knows what they want but has not yet done the work of describing it."

The Interrogation

She turned the laptop back toward him and folded her hands.

"Tell me about the pipeline. What does it do?"

"It processes customer transaction records. Reads from a database, applies some business logic, writes results to a reporting table."

"How many records?"

"On small runs, a few thousand. On the monthly batch — around four million."

"And the performance issue. What exactly is happening?"

"The monthly batch is timing out. It used to complete in about forty minutes. Now it's taking over three hours and failing halfway through."

"When did this change?"

Timothy paused. "About three weeks ago."

"What changed three weeks ago?"

Another pause — longer this time. "We added a new validation step. For regulatory compliance."

Margaret looked at him steadily. "And you gave Claude Code the prompt: fix the performance issue in my data processing pipeline."

He had the grace to look slightly embarrassed. "When you say it like that—"

"I say it like that because that is what you wrote." She picked up her pen. "Claude Code is not a mind reader. It does not know about your four million records, your regulatory validation, your three-hour timeout, or the fact that this began three weeks ago. You handed it a problem with no context, no constraints, and no indication of what success looks like. What do you imagine it would produce?"

"Something generic," he admitted.

"Something generic," she confirmed. "Possibly something plausible-sounding but entirely wrong for your specific situation. And you would have to spend an hour discovering that, when five minutes of careful thinking at the start would have prevented it entirely."

The Four Questions

She drew a small grid on her notepad — four boxes.

"Before you write any prompt for a real engineering problem," she said, "you answer four questions. Not in the prompt itself necessarily — but in your own mind first, and then reflected in what you write."

She filled in the boxes as she spoke.

"First — what is the context? What system are we working in, what does it do, what are its constraints? Claude Code needs to understand the world the problem lives in."

"Second — what is the specific problem? Not 'performance issue.' The pipeline processes four million records monthly, recently began timing out after three hours, previously completed in forty minutes, change coincided with addition of a validation step."

"Third — what have you already tried or considered? This is the question most developers skip. If you have already ruled out certain approaches, say so. If you have a theory, share it. You are not asking Claude Code to think from scratch — you are asking it to think alongside you."

Timothy was writing now. Margaret continued.

"Fourth — what does a good solution look like? What are the constraints? Must it complete within a certain time? Must it not change the output format? Are there parts of the codebase it must not touch? Define success before you start, or you will not recognise it when you see it."

She set down her pen. "Now rewrite your prompt."

The Rewrite

Timothy was quiet for several minutes. Margaret drank her tea and did not hurry him. Good thinking could not be rushed, and she had learned long ago that silence was often more productive than assistance.

He turned the laptop toward her.

"I have a data processing pipeline in Python that reads customer transaction records from a PostgreSQL database, applies business logic validation, and writes results to a reporting table. On monthly batch runs of approximately four million records, the pipeline recently began timing out after three hours — it previously completed in forty minutes. The change coincided with the addition of a new regulatory validation step three weeks ago. I suspect the validation logic may be running a database query inside a loop, but I have not confirmed this. The solution must not change the output format or the table schema. Can you help me identify the likely bottleneck and suggest an approach to fix it?"

Margaret read it carefully. All the way through, twice.

"Better," she said. "Much better."

"Just better?"

"Significantly better," she allowed. "You have given it context, a specific problem, a timeline, a hypothesis, and a constraint. Claude Code can now do something genuinely useful with this." She paused. "One addition I would suggest — tell it what you want first. Not at the end."

"What do you mean?"

"You buried the actual request in the last sentence. Lead with the outcome you want, then provide the context. Something like: I need to diagnose and fix a performance regression in a Python data pipeline — then everything else follows. The tool reads from the beginning. Give it direction before you give it detail."

Timothy made the adjustment. The prompt now opened with a clear statement of intent, followed by everything he had already written.

"There," Margaret said. "Now you have a prompt worth sending."

What Changed

"Can I ask something?" Timothy said. "The second prompt is so much longer. Is longer always better?"

"No," Margaret said immediately. "Length is not the virtue. Precision is the virtue. Your second prompt is longer because your first prompt was missing essential information. If your first prompt had been precise and complete, it would have been the right length." She looked at him steadily. "The question to ask is not have I written enough? It is does this contain everything Claude Code needs to help me? Sometimes that is two sentences. Sometimes it is a paragraph. The problem determines the length, not the other way around."

Timothy nodded slowly. "So the prompt is really just... clear thinking written down."

"Exactly that," Margaret said. "That is all it has ever been. The developers who struggle with Claude Code are very often not struggling with the tool — they are struggling with the thinking that should come before the tool. The prompt reveals the quality of your understanding. If your understanding is vague, the prompt will be vague, and the output will be vague."

"And if my understanding is clear—"

"The prompt will be clear, and Claude Code will do remarkable work." She closed her notepad. "This is why I said in our first conversation that the tool amplifies what you bring to it. Nowhere is that more visible than in the prompt."

The Hypothesis Worth Sharing

"You mentioned a hypothesis," Margaret said. "That the validation logic might be running a database query inside a loop. Do you actually believe that?"

"It's the most likely thing," Timothy said. "The validation step checks each transaction against a reference table. If it's doing that one record at a time instead of batching—"

"Then you have an N+1 query problem," Margaret said. "Four million individual database calls instead of a small number of efficient batched queries."

"Which would explain everything."

"It would explain a great deal, yes." She looked at him. "When you have a hypothesis, share it. Not because Claude Code needs your permission to think — but because your hypothesis is information. It tells the tool where to look first, which approaches are worth exploring, and which are likely dead ends. A shared hypothesis is not a constraint. It is a gift."

Timothy looked at the revised prompt on his screen. "I gave it the gift."

"You did." Margaret allowed herself a small smile. "And if your hypothesis is wrong, Claude Code will likely tell you why — which is also useful. You do not lose anything by sharing your thinking. You only gain."

Before He Sent It

"One more thing," Margaret said, just as Timothy was about to hit enter. "Read it aloud."

He looked up. "I beg your pardon?"

"Read the prompt aloud. Before you send it."

He did — slightly self-consciously, but thoroughly. Halfway through, he stopped.

"I said recently twice," he said.

"You did."

"And I never specified which table the results are written to."

"No."

He made both corrections without being asked. Margaret said nothing. She did not need to.

When he sent it, the prompt was clean, precise, and complete. Claude Code's response came back detailed, specific, and directly useful — identifying the likely N+1 pattern, suggesting a batched lookup approach, and flagging two other areas worth investigating.

Timothy read it with the focused expression of someone who understood what they were looking at.

"It knew exactly where to look," he said quietly.

"Because you told it exactly where to look," Margaret said. "That is the partnership. You bring the context and the thinking. It brings the breadth and the speed. Neither is sufficient alone."

She picked up her tea.

"The first prompt is not the beginning of the work, Timothy. It is the end of the thinking. Get the thinking right first, and everything that follows will be better for it."

Outside, London was going about its afternoon. Inside the library, a developer had just learned something that would serve him for the rest of his career — not a trick, not a shortcut, but a discipline.

The discipline of thinking clearly before asking.

Next episode: Margaret and Timothy explore what happens when Claude Code gets it wrong — confidently, convincingly, and completely. How to catch the errors that look like answers.

The Secret Life of Claude Code publishes on tech-reader.blog every other day.

If this series is useful to you, share it with a developer who needs to hear it.

Aaron Rose is a software engineer and technology writer at tech-reader.blog. For explainer videos and podcasts, check out Tech-Reader YouTube channel.

Happy Pi Day

Aaron Rose — Fri, 06 Mar 2026 02:43:22 +0000

A Pi Day Celebration with Margaret and Timothy from The Secret Life of Pi

March 14th — 3.14159...

Margaret is a senior software engineer. Timothy is her junior colleague. They work in a grand Victorian library in London — the kind of place where old mysteries and new discoveries share the same shelves. Today is the 14th of March. Margaret has been waiting for it.

The Number on the Chalkboard

Timothy arrived to find something unusual. Margaret had pulled a small chalkboard from the storage room — the kind with a wooden frame and a little groove for chalk dust — and propped it against the fireplace. On it, in her precise handwriting, was a single symbol.

"You've decorated," he said.

"I have marked the occasion," she said, pouring tea without looking up. "Sit down, Timothy. Today we are not talking about code."

He sat. "What are we talking about?"

She set a cup in front of him and looked at the chalkboard with something that could only be described as fondness.

"The most remarkable number in the universe," she said.

What Pi Actually Is

"I know what pi is," Timothy said, a little defensively. "Three point one four one five nine. Circles. Circumference divided by diameter."

"You know what pi does," Margaret said. "That is not the same as knowing what it is."

He opened his mouth and closed it again.

"Pi is the ratio of a circle's circumference to its diameter," she continued. "Every circle that has ever existed, from a ripple in a pond to the orbit of a planet, obeys this ratio exactly. You cannot draw a circle — in sand, in code, in the fabric of space — without pi being present. It was there before we discovered it. It will be there long after we are gone."

Timothy looked at the symbol on the chalkboard with fresh eyes. "It's a constant."

"It is the constant. Or one of them." She settled back. "But here is where it gets interesting. Pi is not a tidy number. It is not three. It is not three and a bit. It is 3.14159265358979... and it continues forever, without repetition, without pattern, without end."

"Forever," Timothy repeated. "How do we know?"

"Because mathematicians have proven it. Pi is what we call irrational — it cannot be expressed as a simple fraction. And it is transcendental — it cannot be the solution to any ordinary algebraic equation. It exists outside the neat categories we try to impose on numbers. It simply is."

The Long Hunt

Timothy wrapped his hands around his teacup. "How long have we known about pi?"

Margaret smiled. This was her favourite part.

"Babylonian mathematicians were using approximations of pi nearly four thousand years ago. The ancient Egyptians got remarkably close. Archimedes, working in Syracuse around 250 BCE, was the first to calculate it rigorously — he drew polygons inside and outside a circle, with more and more sides, and squeezed pi between them like a vice until he had it to two decimal places." She paused. "He did this by hand. With geometry. No calculator. No computer. Just a brilliant mind and an obsession with precision."

"Two decimal places by hand," Timothy said quietly. "That's extraordinary."

"It gets better. In the fifth century, a Chinese mathematician named Zu Chongzhi calculated pi to seven decimal places — a record that stood for nearly a thousand years. Seven decimal places. By hand." She shook her head slowly, not in disbelief but in admiration. "These were people who understood that precision mattered. That the universe deserved to be measured carefully."

Why It Shows Up Everywhere

"Here's what I've never understood," Timothy said, leaning forward. "Why does pi appear everywhere? Not just in circles. I've seen it in physics, in probability, in statistics. It turns up in the most unexpected places."

"Ah," Margaret said, and her eyes lit up. "Now you are asking the right question."

She stood and went to the window, looking out at the London street below — the curve of the road, the arc of a gas lamp, the circular face of a clock tower in the distance.

"Pi is not merely about circles. Pi is about the deep structure of curves, waves, and cycles. Wherever something in nature oscillates — a pendulum, a sound wave, a light wave, the orbit of a moon — pi is embedded in the mathematics that describes it." She turned back to face him. "When you calculate the probability of certain random events, pi appears. When you analyse the distribution of prime numbers, pi appears. It is as if the universe has a favourite number and keeps writing it into everything."

"That's almost unsettling," Timothy said.

"It is beautiful," Margaret corrected gently. "It suggests that reality has an underlying coherence — that the same mathematical truths appear across wildly different phenomena because they share a common deep structure. Pi is one of the threads that runs through everything."

The Infinite Decimal

Timothy stared into his tea for a moment. "The fact that it never ends and never repeats. Does that bother you?"

Margaret considered this seriously, the way she considered everything.

"It used to," she said. "When I was young, I wanted mathematics to be tidy. Finite. Resolved. Pi offended my sense of order." She smiled at the memory. "Then I came to understand that the infinite decimal is not a flaw. It is a feature. It means that no finite description can fully capture pi. It always has more to say. There is always another digit, another layer of precision available to anyone willing to look for it."

"How many digits have we calculated?"

"As of recent years, over one hundred trillion digits." She let that settle. "One hundred trillion. Supercomputers running for months. And pi has not repeated. It has not resolved into a pattern. It simply continues, indifferent to our curiosity, offering up new digits one at a time like a book that never ends."

Timothy was quiet for a long moment.

"And we celebrate this," he said finally, "on March fourteenth."

"Three, fourteen," Margaret said. "3.14. The mathematician William Jones first used the Greek letter π to represent it in 1706. The physicist Larry Shaw organised the first proper Pi Day celebration in 1988 at the San Francisco Exploratorium." She glanced at the chalkboard. "It has been a tradition worth keeping ever since."

What Pi Teaches Us

"Can I ask something that might sound strange?" Timothy said.

"Those are usually the best questions."

"What does pi actually teach us? As developers, as engineers, as people?"

Margaret thought about this for longer than usual. Outside, a light rain had begun to fall, and the sound of it against the library windows was the only sound in the room.

"Pi teaches us that some things are inexhaustible," she said finally. "That precision has no ceiling — you can always know more, measure more carefully, compute more digits. It teaches us that beauty and utility are not opposites — pi is both achingly beautiful and relentlessly practical. It turns up in the code we write, the signals we process, the graphics we render."

She looked at the symbol on the chalkboard one more time.

"And perhaps most importantly — pi teaches us humility. Here is a number that humanity has pursued for four thousand years with everything we have. Our sharpest minds. Our fastest machines. And it remains infinite, irrational, transcendental, and inexhaustible." She picked up her tea. "Some things are larger than our ability to contain them. That is not a reason for despair. It is a reason for wonder."

Timothy looked at the chalkboard for a long time.

"Happy Pi Day, Margaret," he said quietly.

She raised her cup.

"Happy Pi Day, Timothy."

Outside, London went about its day, quite unaware that in one particular library, two developers had spent the morning with the most beautiful number in the universe — and were both, in their own ways, the better for it.

π = 3.14159265358979323846264338327950288...

...and counting. Always counting.

From the Victorian library, with wonder. Happy Pi Day — March 14th.

Aaron Rose is a software engineer and technology writer at tech-reader.blog. For explainer videos and podcasts, check out Tech-Reader YouTube channel.

DEV Community: Aaron Rose

The Secret Life of Go: Error Handling (Part 2)

The Custom Error Struct

The Extraction (errors.As)

The Architect's Rule

Key Concepts Introduced:

The Secret Life of Go: Error Handling

The Sentinel Error

The Wrapping Problem (%v vs %w)

Key Concepts

The Secret Life of Claude Code — The Language You Don't Know

The File

What Claude Code Can Do in a Language You Don't Know

The Three Things You Actually Have

The Honest Limits

The Right Way to Ask

Before He Left

The Secret Life of Go: Generics

The Type Parameter ([K, V])

The Generic Methods

The Architect's Constraint

Key Concepts from Episode 29

The Secret Life of Claude Code: Reading Code You Didn't Write

The Inheritance

Why Unfamiliar Code Resists Reading

The Two Passes

The Hypothesis Model

What to Do With the Middle

The Question of Trust

Before He Left

Happy Pi Day!

The Secret Life of Claude Code: The Art of the Follow-Up

The Almost

Why Developers Don't Follow Up

What a Follow-Up Actually Is

The Diagnostic Read

The Follow-Up Prompt

The Conversation, Not the Transaction

Before He Left

The Secret Life of JavaScript: The Observer

The Secret Life of Claude Code: When Claude Code Gets It Wrong

What Timothy Was Proud Of

The Shape of the Problem

Confidence Is Not a Signal

The Three Failure Modes

What Review Actually Means

Before He Closed the Laptop

The Secret Life of JavaScript: The Scroll

Frozen

The Compositor Thread

A High-Speed Train

A Contract With the Browser

Running Fast

The Secret Life of Claude Code: The First Prompt

What Timothy Brought In

The Interrogation

The Four Questions

The Rewrite

What Changed

The Hypothesis Worth Sharing

Before He Sent It

Happy Pi Day

March 14th — 3.14159...

The Number on the Chalkboard

What Pi Actually Is

The Long Hunt

Why It Shows Up Everywhere

The Infinite Decimal

What Pi Teaches Us

The Extraction (`errors.As`)

The Wrapping Problem (`%v` vs `%w`)

The Type Parameter (`[K, V]`)