Clean Code in the Age of AI: Why Machines Need Comments Too

_Disclaimer: These are my personal thoughts and observations, based on my experience working with AI tools and modern development practices. _ Since 2008, when Robert C. Martin released Clean Code, developers have lived by a few golden rules: "Clean code speaks for itself" Avoid comments — just write better code Tests should be self-explanatory Use small functions and abstract aggressively These ideas made a lot of sense — for humans. They were born in an era where the main audience of your code was another developer reading it line-by-line. But here's the shift - We're no longer writing code just for humans. We're writing it for AI agents, too... Protocols like Model Context Protocol (MCP) and Agent-to-Agent (A2A) communication are pushing AI beyond "just chat". These protocols aim to give machines enough structured knowledge and context to reason about systems, interact with them, and even modify or debug code on your behalf. But there's a catch: ❌ No comments in tests? An AI agent won’t know why the test exists or what edge case it’s trying to guard against. ❌ Missing documentation? Humans might guess what a class or module does. AI doesn’t. Without docs, APIs become black boxes. ❌ Over-abstracted “clean” code? Machines struggle when logic is split across many files and layers. Too many indirections = confusion.

Apr 11, 2025 - 18:11

Clean Code in the Age of AI: Why Machines Need Comments Too

_Disclaimer: These are my personal thoughts and observations, based on my experience working with AI tools and modern development practices.
_

Since 2008, when Robert C. Martin released Clean Code, developers have lived by a few golden rules:

"Clean code speaks for itself"
Avoid comments — just write better code
Tests should be self-explanatory
Use small functions and abstract aggressively

These ideas made a lot of sense — for humans. They were born in an era where the main audience of your code was another developer reading it line-by-line.

But here's the shift -
We're no longer writing code just for humans.

We're writing it for AI agents, too...

Protocols like Model Context Protocol (MCP) and Agent-to-Agent (A2A) communication are pushing AI beyond "just chat". These protocols aim to give machines enough structured knowledge and context to reason about systems, interact with them, and even modify or debug code on your behalf.

But there's a catch:

❌ No comments in tests?
An AI agent won’t know why the test exists or what edge case it’s trying to guard against.

❌ Missing documentation?
Humans might guess what a class or module does. AI doesn’t. Without docs, APIs become black boxes.

❌ Over-abstracted “clean” code?
Machines struggle when logic is split across many files and layers. Too many indirections = confusion.