Things You Should Never Do, Part I

In the AI Story

The essay emerged from Spolsky's observation of Netscape's 1997 decision to rewrite Netscape Communicator from scratch as a new codebase that became Mozilla. The rewrite took three years to produce a shippable browser. During those three years, Microsoft's Internet Explorer became the dominant browser. Netscape's market share, which had been above 80% in 1996, was below 10% by 2000. The company was acquired by AOL. The rewrite was not the only cause of Netscape's decline — antitrust litigation, Microsoft's bundling, and other factors contributed — but Spolsky's argument was that the rewrite was the decisive technical error, the choice that guaranteed Netscape could not respond to competitive pressure during the three years it consumed.

The generalizable insight was about what existing code contains that is invisible to someone reading it. A working production codebase, Spolsky argued, is not primarily a document of what its designers intended. It is a record of what reality demanded. The function that looks unnecessarily complex probably handles an edge case someone discovered at 3 a.m. in production. The line of code with an inscrutable comment probably represents a workaround for a bug that took a week to diagnose. The ugliness of old code is not evidence that it is bad code; it is evidence that the code has been educated by the world it runs in.

The AI-generated code parallel is direct. AI-generated code is, by definition, code that has not been educated by reality. It has been generated from patterns in training data — from code that was educated by reality, but whose educational context is not preserved in the generation. The AI produces what looks like clean code, because the ugliness of real production code is exactly the kind of pattern that is underrepresented in curated training data. The curators selected for examples that looked like good code, not examples that had been bruised by reality. The AI's output inherits the aesthetic without the education.

Spolsky's original warning was about human teams choosing to rewrite their own codebases. The AI-era version of the warning is about human teams choosing to generate codebases from scratch, over and over, at rates that make every project a rewrite. The costs Spolsky documented — the three years Netscape lost, the rediscovery of every lesson its old code had already learned — are distributed across the AI-era software industry in smaller increments, one project at a time, invisible in aggregate but immense in total.

Origin

The essay was published April 6, 2000, on joelonsoftware.com. 'Part I' in the title implied a series, but Spolsky never published subsequent parts, which has become part of the essay's lore. The essay remains one of the most cited pieces of software engineering writing and is frequently referenced in discussions of technical debt, rewrites, and legacy code management.

Key Ideas

Old code is educated by reality. Its apparent ugliness is evidence of the lessons it has learned, not evidence of its authors' incompetence.

Rewrites pay the full cost again. The education reality provided must be repaid, at the same cost, or the new code will fail.

The knowledge is implicit. It is not documented, because no one documented it; it exists only in the code itself.

Clean code is not necessarily better. Cleanliness can indicate that the code has not yet been tested by reality.

AI-generated code is the ultimate clean rewrite. Its educational context is training data, not production, and the distinction matters enormously when the code encounters real conditions.