Topic domain
Software Engineering
Practices for building and changing software over time.
- Articles
- 80
- Clusters
- 8
- Foundational
- 24
- Intermediate
- 32
- Advanced
- 24
Turning problems into specified behavior.
- Preconditions and Postconditions as the Function Contract
- Specifying Behaviour as a State Machine with Guards
- Inductive Invariants Over Reachable States
- Specifying Partial Failure, Atomicity, and Retry Semantics
- Liveness and Fairness in Temporal Specifications
- Refinement: When an Implementation Satisfies a Specification
Testing
10Test design, doubles, and suite economics.
- Deriving Test Inputs from Equivalence Partitions and Boundaries
- Test Oracles and Where Expected Values Come From
- Stubs, Fakes, and Mocks: What Each Double Actually Verifies
- Fixture Isolation and the Cost of Shared Test State
- Coverage Criteria and What They Cannot See
- Property-Based Testing and How Shrinking Finds the Minimal Case
Refactoring
10Behavior-preserving change at scale.
- The Equivalence Relation That Refactoring Depends On
- Extract Function and the Preconditions the Compiler Checks
- Why Textual Renaming Fails and Syntax Trees Do Not
- Characterization Tests as a Refactoring Safety Net
- Seams: The Places Where Behavior Can Be Substituted
- Branch by Abstraction and the Cost of Two Live Paths
Code Review
10Defect detection and knowledge transfer.
- What a Unified Diff Hunk Actually Encodes
- Diff Algorithm Choice and the Noise It Adds to a Review
- Splitting a Change into Units That Can Be Reviewed Independently
- Which Defects a Diff Reader Can Actually Detect
- The Semantics of a Code Review Approval
- Reviewing Tests in the Same Diff as the Code
Branching models and history hygiene.
- What a Commit Contains and Why Its Hash Is Content-Addressed
- Three-Way Merge and How the Merge Base Is Chosen
- Fast-Forward, Merge Commits, and What First-Parent History Hides
- Rebase as Patch Replay and Why Every Id Changes
- Branch Lifetime and the Cost of Divergence
- Squash, Fixup, and How a Commit Series Is Composed
Dependencies
10Selection, upgrades, and supply risk.
- What a Version Range Selects: The Interval Algebra Behind Caret and Tilde
- Resolution as Constraint Search: Why Dependency Solving Is NP-Hard
- Lockfiles: Recording the Resolved Graph Without Re-Resolving It
- When One Graph Contains Several Copies of the Same Package
- Install Scripts: The Code That Runs Before the Package Does
- How a Package Name Becomes a Download: Registry Lookup Order and Confusion
Reference material that stays true.
- The Contract Elements a Function Reference Entry Has to State
- How Doctest Decides Whether a Documented Example Passed
- Changelogs as a Curated Projection of Commit History
- Heading Anchors and the Silent Failure of Fragment Links
- What an API Doc Generator Can Recover From Source Alone
- Stable Error Codes as Documentation Identifiers
Planning, estimation, and incident learning.
- Cycle Time, Work-in-Progress Limits, and Little's Law in Delivery Queues
- Aggregating Task Estimates: Why Summed Ranges Come Out Too Narrow
- Critical Path, Float, and Why the Longest Chain Sets the Date
- Calibrating Interval Estimates Against Recorded Outcomes
- Forecasting Completion Dates from Historical Throughput
- Severity Tiers, Escalation Timers, and the Cost of a Page
All Software Engineering articles
- Oct 25, 2026 Signed Repository Metadata and the Compromise-Resistant Update Protocol Why a signature on the artifact is not enough, how role-based metadata separates signing keys by function, and what the freshness and freeze defences cost in round trips.
- Oct 6, 2026 Repository-Scale Codemods and the Review Problem A codemod that rewrites ten thousand call sites produces a diff nobody can read. Sharding, mechanization proofs, and a declarative matcher are what make the change reviewable.
- Oct 2, 2026 Stubs, Fakes, and Mocks: What Each Double Actually Verifies The distinction between state verification and interaction verification, why a hand-written fake survives refactoring better than a mock, and what mock assertions couple.
- Sep 30, 2026 Migrating Stored Data While Both Formats Are Live A dual-write phase lets code change before data does, but it trades a clean cutover for a consistency problem. Ordering, backfill, and verification decide whether it holds.
- Sep 26, 2026 Suite Economics: Runtime, Feedback Delay, and Test Selection Why the value of a test decays with the time it takes to report, how to partition a suite by feedback latency, and what selective running buys and costs.
- Sep 5, 2026 Branch Lifetime and the Cost of Divergence How branch age affects conflict size, merge base distance, and review quality, and what integration frequency changes mechanically rather than culturally.
- Sep 5, 2026 Deterministic Checks That Keep a Documentation Build Honest A build can verify markup, references, examples, and terminology without judgement. Separating those mechanical assertions from editorial taste is what makes a failing build mean something.
- Sep 1, 2026 Three-Way Merge and How the Merge Base Is Chosen Why merging compares two tips against a common ancestor rather than against each other, how the base is selected when history is criss-crossed, and where the approach loses information.
- Aug 26, 2026 Exhaustive State Exploration and What a Bounded Model Proves How model checking enumerates reachable states, why a bound is a parameter of the claim rather than a shortcut, and how to read a counterexample as a requirement defect.
- Aug 24, 2026 Static Analysis Findings as a Review Signal What a linter or analyser can prove about a diff, how findings are ranked so that reviewers see the few that matter, and why suppression is the mechanism that decides whether any of it works.
- Aug 18, 2026 What a Version Range Selects: The Interval Algebra Behind Caret and Tilde How comparators, disjunction, and prerelease exclusion turn a version constraint into a concrete set of versions, and where the range language stops describing compatibility at all.
- Aug 5, 2026 The Contract Elements a Function Reference Entry Has to State A signature fixes argument types and little else. Preconditions, ownership, failure modes, and concurrency guarantees are separate obligations that the reference entry has to record explicitly.
- Aug 1, 2026 What a Unified Diff Hunk Actually Encodes How the hunk header, the minus and plus blocks, and the context window are produced, and which parts of a change a line-oriented diff cannot represent at all.
- Jul 27, 2026 Resolution as Constraint Search: Why Dependency Solving Is NP-Hard How a resolver chooses versions for a whole graph at once, why the general problem resists polynomial algorithms, and which practical strategies keep real graphs solvable.
- Jun 29, 2026 What a Commit Contains and Why Its Hash Is Content-Addressed The four object types, the exact bytes a commit hash covers, and why editing one old file rewrites every descendant hash.
- Jun 17, 2026 Error Budgets as a Release Gate: The Arithmetic Behind the Freeze Converting a service level objective into a measured allowance of failure, normalising it with burn rate, alerting on two windows at once, and the places where the arithmetic stops matching user experience.
- Jun 5, 2026 Fast-Forward, Merge Commits, and What First-Parent History Hides When a ref move is enough to integrate a branch, when a merge commit is required, and how first-parent traversal changes the history a reader sees.
- May 22, 2026 Aggregating Task Estimates: Why Summed Ranges Come Out Too Narrow Why adding per-task ranges produces an interval that is too tight for the whole job, how skew and correlation break the diversification argument, and what to compute instead.
- May 22, 2026 Mutation Testing as a Measure of Assertion Strength How generated mutants expose tests that execute code without checking it, which mutation operators matter, why equivalent mutants cap the score, and what the technique costs.
- May 16, 2026 Lockfiles: Recording the Resolved Graph Without Re-Resolving It What a lockfile stores beyond version numbers, how it stays consistent with the manifest, and why regeneration is a different operation from installation.
- Apr 19, 2026 Heading Anchors and the Silent Failure of Fragment Links A fragment link is resolved in the browser and never requested from the server, so a renamed heading breaks every inbound reference without producing a single 404.
- Apr 16, 2026 Stacked Changes and the Mechanics of Incremental Review How a chain of dependent changes lets each diff be read against its own base, what happens when the bottom of the stack changes, and why restacking is the expensive step.
- Apr 13, 2026 How Doctest Decides Whether a Documented Example Passed A transcript in a docstring is compared against captured output by a specific set of rules. Understanding those rules explains why examples drift and which ones cannot be verified at all.
- Apr 11, 2026 Review Metrics and the Confounders That Invert Them Why latency, comment density, and approval counts measure queueing and authorship as much as review quality, and which quantities remain interpretable under those confounders.
- Mar 31, 2026 Forecasting Completion Dates from Historical Throughput Resampling the observed rate of finished work to produce a distribution of completion dates, and the assumptions about scope, unit, and independence that decide whether the answer means anything.
- Feb 26, 2026 Advisory Ranges, Reachability, and Deciding a Vulnerability Does Not Matter How advisory databases express which versions are affected, why a version range in an advisory is not the same claim as an exploitable dependency, and what evidence supports suppressing a finding.
- Feb 25, 2026 Branch by Abstraction and the Cost of Two Live Paths Replacing a widely used component without a long-lived branch means running both implementations behind one interface. The interface, not the code, is what has to be designed.
- Feb 20, 2026 Rebase as Patch Replay and Why Every Id Changes How rebase computes the commits to replay, why the new commits are not the old ones, and what information the replay cannot carry across.
- Jan 29, 2026 The Semantics of a Code Review Approval An approval is a statement with an unstated scope: which revision it applies to, which claims it vouches for, and how it goes stale when the change moves underneath it.
- Jan 17, 2026 Install Scripts: The Code That Runs Before the Package Does What package managers execute at install time, why lifecycle hooks exist, and how their privilege, ordering, and failure semantics make them a separate trust boundary from the code being installed.
- Jan 11, 2026 Conflict Markers, Merge Drivers, and Recorded Resolutions How conflict markers encode the three inputs, how an attribute-selected merge driver replaces the line-based algorithm, and how rerere replays a resolution it has seen before.
- Jan 10, 2026 Liveness and Fairness in Temporal Specifications Why safety properties need only one bad state to fail while liveness needs an infinite execution, and how a fairness assumption turns a starving scheduler into a specification bug.
- Jan 6, 2026 Test Oracles and Where Expected Values Come From Why deciding whether an observed result is correct is harder than producing the input, and the five practical oracle constructions with their failure modes.
- Oct 2, 2025 Sources of Nondeterminism That Make Tests Flaky The mechanisms behind intermittent test failures — scheduling, clocks, unordered iteration, unseeded randomness — and the controls that make each source reproducible rather than merely rarer.
- Sep 5, 2025 Splitting a Change into Units That Can Be Reviewed Independently Why the unit of review should be a reversible intent rather than a file or a commit, how mixed changes produce review deadlock, and what splitting costs in history.
- Aug 23, 2025 Refinement: When an Implementation Satisfies a Specification How refinement relates an abstract specification to concrete behaviour, why stuttering steps and history variables make the relation provable, and where refinement forbids implementation freedom.
- Aug 12, 2025 Serving Several Documentation Versions From One URL Space Versioned documentation is a URL design problem before it is a content problem. Path layout, redirect policy, relative links, and canonical hints decide whether a reader stays on the release they are running.
- Aug 9, 2025 Extract Function and the Preconditions the Compiler Checks Extraction is presented as a mechanical edit, but it is only safe when the extracted body captures no free variables, no control flow, and no implicit receiver.
- Jul 28, 2025 Inductive Invariants Over Reachable States Why an invariant that holds initially and is preserved by every step still needs an induction hypothesis, and how the strengthening problem makes proofs fail.
- Jul 17, 2025 What an API Doc Generator Can Recover From Source Alone Parsing and runtime introspection produce different documentation from the same code. Which one a toolchain uses decides what it can see, what it silently omits, and what it can never know.
- Jul 11, 2025 Bisect Over a Rewritten History How bisect picks the next commit to test, why merge-heavy and rewritten histories distort the search, and what makes a bisect result trustworthy.
- Jul 6, 2025 Calibrating Interval Estimates Against Recorded Outcomes What an eighty percent interval promises, how coverage is measured on small samples, why width must be scored alongside the hit rate, and how reference classes supply the correction.
- Jun 17, 2025 Specifying Partial Failure, Atomicity, and Retry Semantics How a contract states what survives a crash mid-operation, why idempotency keys must be chosen by the caller, and where at-least-once delivery forces deduplication.
- May 3, 2025 Expand, Migrate, Contract: Changing an Interface Without a Flag Day When callers cannot be changed in one deploy, the change is split into three phases that are each independently safe: add the new shape, move every user, remove the old.
- Mar 21, 2025 Yanking, Deprecation, and Retraction: Withdrawing a Version After Publication The three distinct ways a publisher can withdraw a release, what each does to existing lockfiles and fresh resolutions, and why immutability is the property they all trade against.
- Mar 16, 2025 Changelogs as a Curated Projection of Commit History A changelog is not a formatted log. It selects changes by who observes them, classifies them against a version bump, and states consequences that no commit message contains.
- Feb 24, 2025 Ranking Documentation Search When the Query Is an Error String Documentation queries are lookups, not explorations. Identifier tokenisation, field weighting, and version duplication decide whether the entry a reader needs appears at all.
- Feb 11, 2025 Packfiles, Delta Chains, and What Garbage Collection Actually Deletes How loose objects become delta-compressed packs, why delta chains are depth-limited, and how reachability decides what survives a prune.
- Dec 8, 2024 Reviewing Tests in the Same Diff as the Code A test written beside its implementation tends to assert what the code does rather than what it should do, and the diff is where that circularity becomes visible.
- Aug 16, 2024 Cycle Time, Work-in-Progress Limits, and Little's Law in Delivery Queues How the identity L = lambda W ties items in flight to delivery time, why operating near full capacity inflates waiting, and how to size a work-in-progress limit from a target cycle time.
- Aug 1, 2024 Fixture Isolation and the Cost of Shared Test State How ordering dependencies and leaked state turn a suite into a fragile sequence, and the four isolation strategies that restore independence at different prices.
- Jun 18, 2024 How a Package Name Becomes a Download: Registry Lookup Order and Confusion The chain from a bare name in a manifest to a fetched artifact, how registries and scoped namespaces are consulted in order, and why that order is exploitable.
- Jun 15, 2024 Decision Tables and Rule Completeness in Policy Specifications How a decision table exposes overlapping and missing rules in eligibility logic, why hit policies change behaviour, and what completeness costs as conditions multiply.
- Jun 13, 2024 Decomposing Recovery Time into Detection, Diagnosis, and Mitigation Why a single mean time to recovery mixes intervals with different floors and different distributions, how concurrent incidents queue behind one responder, and how to measure each phase without corrupting the comparison.
- Jun 3, 2024 Merge Queues and What Speculative Testing Actually Proves How a queue serialises candidate merges, tests each against the current tip rather than its own base, and why batching candidates changes the meaning of a green result.
- May 16, 2024 Diff Algorithm Choice and the Noise It Adds to a Review Myers, histogram, and patience strategies produce different edit scripts for the same two files, and the choice determines whether a reviewer sees structure or a wall of moved lines.
- May 9, 2024 Postmortem Causation: Triggers, Latent Conditions, and Failed Defences Why a single root cause discards the information needed to prevent recurrence, how counterfactual reasoning behaves in stochastic systems, and how to rebuild a sequence from telemetry with its uncertainty intact.
- May 5, 2024 Detecting Drift Between Reference Material and the Code It Describes Documentation goes stale one claim at a time. Separating checkable claims from judgement calls shows which kinds of drift a build can catch and which only review can.
- Apr 21, 2024 Characterization Tests as a Refactoring Safety Net When code has no specification, the only available oracle is the code itself. Recording current behavior turns a rewrite into a comparison against captured output.
- Mar 26, 2024 Specifying Behaviour as a State Machine with Guards Why a transition table beats prose for event-driven behaviour, how guards resolve overlapping transitions, and what unreachable states reveal about a specification.
- Mar 20, 2024 Squash, Fixup, and How a Commit Series Is Composed The difference between squashing and fixing up, how autosquash matches commits to targets, and what information survives when intermediate commits are collapsed.
- Feb 19, 2024 Coverage Criteria and What They Cannot See How statement, branch, and condition coverage are defined as adequacy criteria, why 100 percent coverage is reachable without testing the requirement, and how data-flow coverage closes part of the gap.
- Feb 7, 2024 Stable Error Codes as Documentation Identifiers Human-readable messages change with wording and locale. A code that never changes, is never reused, and is documented once is what lets callers and support engineers agree on which failure occurred.
- Jan 6, 2024 Property-Based Testing and How Shrinking Finds the Minimal Case Why random generation finds inputs a hand-written table misses, how generators compose, and the reduction algorithm that turns a failing 400-element list into a failing 3-element one.
- Jan 6, 2024 Seams: The Places Where Behavior Can Be Substituted A seam is a point where an edit can change behavior without editing at that point. Link seams, object seams, and preprocessor seams cost different amounts and fail differently.
- Nov 21, 2023 Severity Tiers, Escalation Timers, and the Cost of a Page Separating impact from urgency so a tier is decidable in minutes, converting tiers into acknowledgment and update timers, and the attention economics that decide when paging is the wrong response.
- Nov 8, 2023 The Equivalence Relation That Refactoring Depends On Refactoring is defined as behavior-preserving change, which first requires deciding what counts as behavior. That decision is the whole discipline.
- Nov 7, 2023 Peer Requirements and the Problem of Straddling Two Majors Why some dependencies must be singletons supplied by the consumer, what happens when a package is asked to support two incompatible majors at once, and how the constraint is expressed.
- Sep 18, 2023 Quantifier Scope and Undefined Terms in Requirement Statements Why "all users can see their orders" admits several incompatible readings, how scope ambiguity survives review, and what a rewrite into explicit quantifiers costs.
- May 31, 2023 Preconditions and Postconditions as the Function Contract How a function contract divides obligations between caller and implementer, what a runtime check costs, and where frame conditions and aliasing break the guarantee.
- May 18, 2023 Conformance Testing from a Specification: Distinguishing Sequences How a finite-state specification yields a test suite with a completeness argument, why a distinguishing sequence is necessary, and what the method assumes about the implementation.
- Apr 3, 2023 Cherry-Pick, Patch Identity, and Duplicate Commits Why applying one commit to another branch creates a new id for the same change, how patch-id recognises duplicates, and where that recognition fails.
- Feb 22, 2023 Sequencing Work by Cost of Delay Under Precedence Constraints Why the weight-over-duration ratio is the exact ordering rule for one machine, what changes when dependencies and deadlines enter the model, and where the ratio becomes numerically fragile.
- Jan 27, 2023 When One Graph Contains Several Copies of the Same Package How flat installation trees force duplicate versions into a single directory, what breaks when two copies coexist, and how hoisting decides which copy a require call finds.
- Dec 20, 2022 Critical Path, Float, and Why the Longest Chain Sets the Date How the forward and backward passes compute earliest and latest dates, what total float measures, and why a zero-float path is not necessarily the riskiest one.
- Nov 10, 2022 Model-Based Testing with Explicit State Machines How a reference model plus a generator of valid operation sequences tests stateful systems, why the model must be simpler than the code, and how traces localize a divergence.
- Nov 7, 2022 Deriving Test Inputs from Equivalence Partitions and Boundaries How partition analysis narrows an enormous input space to a small set of cases, why defects concentrate at the lines between classes, and where the technique stops paying.
- Sep 26, 2022 Why Textual Renaming Fails and Syntax Trees Do Not A search-and-replace rename breaks on shadowed names, comments, string literals, and macro bodies. A rename that walks a syntax tree knows which occurrences bind.
- May 21, 2022 What Behavior-Preserving Change Cannot Preserve Cost, stack shape, interleaving, and resource lifetime fall outside the observation set by design. The cases where that exclusion stops being acceptable are the ones that matter.
- Jan 23, 2022 Which Defects a Diff Reader Can Actually Detect Local defects that live inside the changed lines are findable by reading, while invariant violations, races, and resource-lifecycle bugs mostly are not, and the difference sets the ceiling on review.