Software Development on Pauls Blog

A Game Plan for Product and Software Development

Mon, 01 Jan 0001 00:00:00 +0000

A Game Plan for Product and Software Development

The Premise

Most software problems are not technical. A team that consistently delivers working software, adapts to changing requirements, and maintains the capacity to keep improving over time is not doing so because they chose the right framework or the right database. They are doing so because they have internalised a coherent set of practices that compound — each one making the others more effective, and all of them together producing a system that remains comprehensible, changeable, and reliable over its lifetime.

A Pyramid Principle Structure - Software Engineering Excellence

Mon, 01 Jan 0001 00:00:00 +0000

This attempts to apply the McKinsey Pyramid Principle to these software development thoughts and practices.

Amazon Affiliates Link

Buy on Amazon The Pyramid Principle

Software Engineering Excellence — A Pyramid Principle Structure

The McKinsey Pyramid Principle organises thinking from the top down: a single governing idea, supported by a small number of mutually exclusive and collectively exhaustive arguments, each supported by evidence and reasoning. What follows applies that structure to everything covered in this series.

Breaking Down Problems

Mon, 01 Jan 0001 00:00:00 +0000

Breaking Down Problems — Decomposition as a Core Skill

Why It’s a Skill, Not a Step

Decomposition is often treated as a planning activity — something that happens in a refinement session, produces a list of tickets, and is then considered done. The tickets get handed to developers who implement them. This misses what decomposition actually is.

Decomposition is a continuous cognitive skill exercised throughout development — in planning, yes, but also when sitting down to write a test, when deciding where a class boundary should be, when a piece of code resists being understood. The developer who can break a problem down well works differently at every level: they write smaller functions, cleaner interfaces, more focused tests, and smaller PRs. The skill compounds across every scale of work.

Clean Architecture

Mon, 01 Jan 0001 00:00:00 +0000

Clean Architecture

The Core Idea

Clean Architecture, articulated by Robert C. Martin (Uncle Bob), is a way of organising code so that business logic is the centre of the system and everything else — frameworks, databases, UIs, external services — is a detail that can be swapped out or tested independently.

The central rule is the Dependency Rule: source code dependencies can only point inward. Outer layers know about inner layers; inner layers know nothing about outer layers.

Coding Tips — Principles in Practice

Mon, 01 Jan 0001 00:00:00 +0000

Coding Tips — Principles in Practice

These tips are the everyday expression of everything covered in this series — the micro-decisions that, made consistently, produce code that is comprehensible, maintainable, and a pleasure to work in.

Control Flow

Return early to reduce nesting. Every level of nesting is a level of context the reader must hold in working memory. Guard clauses that return or throw early eliminate the nesting that builds up around validation and precondition checks.

Cognitive Load

Mon, 01 Jan 0001 00:00:00 +0000

Cognitive Load — The Hidden Cost of Complexity

What It Is

Cognitive load is the amount of mental effort required to hold and process information at any given moment. The concept comes from educational psychology — John Sweller’s work in the 1980s on how people learn — but it maps directly onto software development, where the primary activity is understanding complex systems well enough to change them safely.

Working memory is the bottleneck. Humans can hold roughly four to seven distinct pieces of information in working memory simultaneously. When that limit is exceeded, comprehension degrades, mistakes increase, and progress slows. The developer who can’t hold the relevant parts of a system in their head at once starts to make changes based on incomplete understanding — which is where bugs come from and where confidence erodes.

Collaborative Development

Mon, 01 Jan 0001 00:00:00 +0000

Collaborative Development — Beyond Strict Pair Programming

(updated to include mentoring and teaching)

The Spectrum of Collaboration

Traditional pair programming has a specific form: two people, one keyboard, one screen, switching between driver and navigator roles. The research behind it is solid — it produces fewer defects, spreads knowledge, and keeps both people focused. But the strict form has real costs: it’s cognitively intense, it doesn’t suit all personality types, and it treats every problem as requiring the same level of collaboration.

Configurable Systems

Mon, 01 Jan 0001 00:00:00 +0000

Configurable Systems and the Right Abstraction

The Core Idea

There is a class of problem where the right move is not to write another solution, but to recognise that you’ve already written several solutions to the same underlying problem and extract the pattern. Instead of building bespoke code repeatedly, you build a framework that models the shape of the problem — and then configure it for each specific instance.

The payoff is significant: new instances of the problem become configuration rather than code. The framework is tested once deeply; each configuration gets a shallow test. Developers working with it operate at the level of the domain concept — star schema, workflow, form, pipeline — rather than the level of implementation detail.

Continuous Integration and Delivery

Mon, 01 Jan 0001 00:00:00 +0000

Continuous Integration and Delivery

The Problem with Infrequent Integration

Imagine two developers working independently on the same codebase for two weeks. They’ve each made hundreds of changes across dozens of files. On day fourteen they attempt to merge. The merge itself might be mechanical — resolving conflicting edits line by line — but the harder problem is behavioural: their changes made assumptions about the system that are no longer true. Tests fail in ways that are hard to diagnose because the surface area of change is enormous. Nobody is sure whether a failure was introduced yesterday or ten days ago.

Decision Making

Mon, 01 Jan 0001 00:00:00 +0000

Decision Making Under Uncertainty

The Problem With Deciding Too Early

Architecture decisions are made at the worst possible time. At the start of a project — when the key decisions feel most urgent — the team has the least information. The domain isn’t fully understood, the usage patterns are hypothetical, the team hasn’t discovered the pain points yet. And yet this is precisely when decisions are made that will shape the system for years.

Domain Modelling

Mon, 01 Jan 0001 00:00:00 +0000

Domain Modelling and Rich Domain Models

The Core Idea

Domain modelling is the practice of capturing the concepts, rules, and behaviour of a business problem in code. A rich domain model goes further — it places business logic inside the domain objects themselves, rather than in surrounding service or use case classes.

The opposite of a rich domain model is an anaemic domain model — objects that are little more than bags of getters and setters, with all logic extracted into services. Martin Fowler describes the anaemic model as an anti-pattern: it has the structure of OOP without the substance.

Feature Flags and Trunk-Based Development

Mon, 01 Jan 0001 00:00:00 +0000

Feature Flags and Trunk-Based Development

The Problem They Solve Together

Continuous Integration demands frequent integration to mainline. Continuous Delivery demands that mainline is always releasable. These two commitments create an immediate tension: what do you do with a feature that takes two weeks to build? You can’t keep it on a branch for two weeks — that defeats CI. But you can’t have a half-built feature in production — that defeats CD.

Keeping Dependencies Up to Date with Renovate

Mon, 01 Jan 0001 00:00:00 +0000

Keeping Dependencies Up to Date with Renovate

The Problem

Every application sits on a foundation of dependencies — libraries, frameworks, build tools, base images. That foundation is not static. Dependencies release updates continuously: new features, performance improvements, bug fixes, and critically, security patches.

The default human response to this is inertia. Updating dependencies takes time, updates occasionally break things, and there is always something more immediately valuable to work on. So updates get deferred. Weeks become months, months become years, and the gap between what you’re running and what’s current grows quietly in the background.

Managing Complexity

Mon, 01 Jan 0001 00:00:00 +0000

Managing Complexity — Keeping Systems Comprehensible

The Two Kinds of Complexity

Fred Brooks introduced the distinction in his 1986 paper No Silver Bullet. It remains one of the most useful ideas in software engineering.

Essential complexity is inherent in the problem itself. A tax calculation system is complex because tax law is complex. A trading platform has complex rules because financial markets have complex rules. A healthcare system handles nuanced workflows because healthcare is genuinely nuanced. This complexity cannot be removed — it can only be managed, modelled, and represented as clearly as possible. Fighting essential complexity is fighting the domain.

Modelling Domains in Kotlin With Value Objects

Mon, 01 Jan 0001 00:00:00 +0000

Modelling Domains in Kotlin With Value Objects

The Problem With Primitives

Every domain has concepts that primitives can represent but cannot express. An email address is a String, but not every String is an email address. An order total is a BigDecimal, but not every BigDecimal is a valid order total — it shouldn’t be negative, it should have a defined currency, and it shouldn’t be mixed with a price in a different currency. A user ID is an Int, but it shouldn’t be added to a product ID, compared to a quantity, or passed where an order ID is expected.

Observability

Mon, 01 Jan 0001 00:00:00 +0000

Observability — Understanding Your System in Production

Why Observability is a Design Concern

Most teams treat observability as something added after the fact — sprinkle some log statements in, wire up a metrics library, declare the system observable. The result is a production system that generates enormous volumes of data while remaining fundamentally opaque when something goes wrong. The logs exist but don’t answer the question being asked. The metrics show something is wrong but not where or why. The traces are missing for the one request that caused the incident.

Reading and Understanding Unfamiliar Codebases

Mon, 01 Jan 0001 00:00:00 +0000

Reading and Understanding Unfamiliar Codebases

Why It’s a Distinct Skill

Most developer education focuses on writing code. Reading code — particularly large, unfamiliar codebases written by people you’ve never met, under constraints you don’t know, solving problems you’re still discovering — is a different activity that receives almost no explicit attention.

Yet it is something every developer does constantly. Joining a new team, picking up an open source library to understand its internals, inheriting a system from a team that no longer exists, returning to your own code after six months. The ability to build an accurate mental model of an unfamiliar system quickly is one of the highest-leverage skills a developer can have, and it is largely learned through trial and error rather than through deliberate practice.

REST and HATEOAS

Mon, 01 Jan 0001 00:00:00 +0000

REST and HATEOAS

REST (Representational State Transfer)

REST is an architectural style for distributed hypermedia systems, first described by Roy Fielding in his 2000 doctoral dissertation. It’s not a protocol or standard, but a set of constraints that, when applied to a web service, produce desirable properties like scalability, simplicity, and modifiability.

The six constraints of REST:

Client-Server — Concerns are separated between the UI/consumer and the data storage/logic. This allows each to evolve independently.

Technical Debt

Mon, 01 Jan 0001 00:00:00 +0000

Technical Debt — Thinking About It Honestly

The Metaphor and Its Limits

Ward Cunningham coined the term “technical debt” in 1992 to describe a specific situation: shipping code that isn’t quite right in order to learn something from real users, with the intention of going back to refactor once that learning has happened. The debt metaphor was deliberate — like financial debt, it accrues interest. The longer you leave the suboptimal code in place, the more every subsequent change that touches it costs.

Technical Documentation — What's Worth Writing Down

Mon, 01 Jan 0001 00:00:00 +0000

Technical Documentation — What’s Worth Writing Down

The Documentation Paradox

Documentation has a reputation problem in both directions. Teams that write too little leave critical knowledge locked in individuals’ heads, where it fades and eventually disappears when people move on. Teams that write too much produce documents that are immediately out of date, never read, and actively misleading — giving readers false confidence that they understand something they don’t.

The failure mode is treating documentation as a uniform activity — either you document everything or you document nothing. The more useful question is: what specific knowledge needs to exist in written form, for whom, and why? Different answers produce radically different kinds of documentation, each with different value and different maintenance costs.

Test-Driven Development

Mon, 01 Jan 0001 00:00:00 +0000

Test-Driven Development (TDD)

The Core Idea

TDD inverts the traditional write-code-then-test workflow. You write a failing test before writing the implementation, then write the minimum code to make it pass, then clean up. The tests don’t just verify correctness after the fact — they drive the design of the code itself.

The Red-Green-Refactor Cycle

This is the heartbeat of TDD. Every small increment of work follows three steps:

Red — Write a test for behaviour that doesn’t exist yet. Run it. It must fail. If it passes, either the behaviour already exists or the test is wrong.

The Spirit of the Craft

Mon, 01 Jan 0001 00:00:00 +0000

The Spirit of the Craft

These documents represent a living collection of my thoughts on building software. While they cover varied topics—from architectural patterns to testing strategies—they are unified by a single perspective: Software is a human-centric endeavor.

The “spirit” of this collection can be distilled into five core convictions:

1. The Primary Constraint is Human Cognition

We build systems that eventually exceed our ability to understand them. Most of our tools—TDD, Clean Architecture, Decomposition—are not about “correctness” in a vacuum; they are defensive measures against cognitive load. We write code for the reader, not the compiler, because the hardest part of software is keeping the mental model in our heads long enough to change it safely.

Writing Code for the Reader

Mon, 01 Jan 0001 00:00:00 +0000

Writing Code for the Reader

The Compiler Is Not Your Audience

Code is written once. It is read many times — by the next developer to work in the area, by a colleague reviewing the PR, by you returning to it six months later with the context entirely gone. The compiler will accept almost anything that is syntactically correct. The human reader is far more demanding, and far more important.