Architecture & design · Book notes
Clean Code, rewritten: which rules still matter when AI writes code?
The second edition rewrote the presentation and kept the rules critics argue about, just as review of AI-written code became how a coding standard gets enforced.
A Sonar survey earlier this year of over 1,100 developers found that AI accounts for ~42% of committed code, but 96% of developers don’t fully trust the code generated by AI. This means the purpose of a coding standard changes from describing the code that people write to describing the code that people review, an increasing portion of which is generated by models.
At a time when the most argued-about software book comes back as a full rewrite, the second edition of Clean Code finally reaching readers in late 2025 (17 years after the first) lands in a world very different from 2008. And so it’s worth asking which of those rules still earn their place in your team’s standard when the model writes the first draft.
Robert Martin describes the new edition as a “complete rewrite” that delivers the same message in an entirely different presentation. The announcement post became one of the biggest book threads r/programming has ever had. The book is split into four parts and 37 chapters, includes examples in seven different programming languages (not just Java), and folds in material that used to be in The Clean Coder and Clean Architecture. The two most telling additions about the moment we’re living in: a chapter called “AIs, LLMs, and God Knows What” and an appendix titled “The Clean Code Debate” that takes a softer tone and says it’s okay to disagree.
Critics say the presentation is new but the style is the same. The Axolot’s Don’t Refactor Like Uncle Bob (Second Edition) review praises the use of modern Java and stepwise refactorings, then shows the same habits that drew criticism in the first edition: tiny functions, turning arguments into instance fields so methods can share state without parameters, and treating comments as a last resort.
The longest-running form of this argument is John Ousterhout’s written exchange with Martin about method length and comments. The first edition suggests functions of two to four lines, and Ousterhout argues that such fine decomposition displaces complexity rather than removing it. This argument deserves more space than I have here (more in A Philosophy of Software Design point and counterpoint).
As a principal cloud architect who has worked with large financial institutions and Fortune 500 companies, I see a coding standard as a review contract rather than a style guide. Banks and insurers often use code review as a form of change control; an auditor may ask “who approved this change and could they understand it?”. If a model is the first author, the reviewer is the only human who needs to understand the change.
The area where AI-written code struggles most is readability. CodeRabbit’s analysis of 470 open-source pull requests found that AI-authored code had about 1.7 times as many issues overall, but over 3 times as many readability issues.. the largest gap in their dataset. This typically manifests as code that looks tidy but doesn’t follow local conventions for naming and structure (CodeRabbit’s report). This is exactly the kind of thing a written standard should capture.
Through this lens, the rules in the book fall into two groups. The key question is: which of these rules would a reviewer block a merge for? The first group helps a second reader and can be checked in review: reveal intent with names, tests as repeatable proof (which get their own chapter in the new edition, “Repeatable Proof”). The second group is taste: functions should be two to four lines, don’t write comments. A linter can count the second group, but passing the linter doesn’t tell the reviewer or auditor anything about whether another person could understand the change.
The postscript to Martin’s own rewrite makes this point more sharply than any survey. At the end of Chapter 2, he fed the cleaned-up code to Grok 3. It returned a version that passed his tests but kept an unnecessary instance variable it had picked up from his code. The model copies the style it’s given, so the contents of your repo end up in every AI-written change, whether you enforce them or not. Which rules belong in the standard agents copy and auditors read?