Copied over from my newsletter…
Some time over the last year I began to notice that Claude Code was omitting comments from the code it was creating for me. I wasn't sure why, but I figured that I had given it this instruction at some point (because it used to be super verbose) and needed to change it.
There is a contingent of developers who believe comments in code are a bad thing because they're a "crutch", and our goal should be to write clean, understandable, readable. I don't agree with that because what I think makes sense will likely make zero sense to you.
But I'm curious what you think. This is the kind of thing I'm going to discuss in the Summer 2026 Cohort that I'm starting up in June/July. If you'd like to know more, head on over and have a look. I have also kicked up a community site dedicated to creating high quality code using AI. I asked about this in a previous email and hundreds of you were interested, so I put it together. Hope you drop by and join up!
Anyway: a few weeks ago, while recording a video on code quality (the Fibonacci one), Claude asked me to actually confirm that I wanted comments written. The wording of that confirmation was really weird, too:
Your instructions on code commenting contradict that of the coding harness, please confirm this is what you want.
I was a bit terse with my reply and asked it what it meant by "coding harness". Thankfully I grabbed a screenshot this time:
At first I was completely vexxed as to how anyone would think this is a good idea, especially when it comes to LLMs! I don't know - maybe I'm entirely wrong on this - but the clearer you can be with an LLM, the better. Why have this instruction? To save tokens?
That seemed likely, but then I remembered an idea a well-known coder was trying to inflict on people many years back:
The proper use of comments is to compensate for our failure to express ourself in code. Comments are always failures. We must have them because we cannot always figure out how to express ourselves without them, but their use is not a cause for celebration. So when you find yourself in a position where you need to write a comment, think it through and see whether there isn’t some way to turn the tables and express yourself in code.
Yeah you know who wrote that. To me, this is filled with hubris, ego, and nonsense. It's also a very good ideal to reach for, unfortunately.
When I was thick into Ruby, the idea was that we wrote "self-documenting prose", bordering on poetry. I remember liking that idea for a week or so, then recognizing it for the precious, egotistical bespoke pourover nonsense that it is.
I suppose none of this matters, anyway, as human involvement in coding is rapidly going away. I don't say that happily, either, because machines need to have rules and process just like we do. What I'm concerned about, mostly, is that no one is pushing AI to do better in terms of long term maintainability and change.
We know this: the easy part is building the thing, the hard part is keeping it running.
Mediocrity is everywhere, by design
When you ask an LLM to write code for you, you will get back a mediocre solution by definition. The LLM uses probability (with some adjustments based on the system prompt and whatever you've told it), and the most probable result is what most people have created.
I don't want to sound like a snob, but I don't think superior, high-quality code is the norm. If it was, it wouldn't be superior would it?
To show you what I mean, I'm going to pick on one of my favorite bits of problematic design patterns: the Repository. The idea is sound, the implementation is almost always crap.
Here's a prompt I gave to Claude, Gemini, and ChatGPT:
I have an ecommerce site that I created using Next.js with a typescript backend. I need to think about data access and a "good", quality approach to the code. What do you recommend? Can you give me some example using Orders, Customers, and Products?
In every case, the answer that came back was "use a repository":
A Repository will work just fine for a smaller application and, to be clear, the pattern itself isn't "bad". The problem comes in when you use data access tools like Drizzle or Entity Framework. These tools implement their own patterns (data mapper and unit of work, respectively), which may or may not align with a repository.
Consider this code:
This is a variation of what was suggested by every one of the LLMs: pass in the data access tool in the form of a live transaction, do the needful, then hand it back.
This is a problem for a number of reasons:
A repository method is supposed to be atomic. If data is mutated, it is persisted at the same time so the repository remains whole.
Passing in a database tool like this is a coupling problem. The repository can't function without it.
This isn't a repository at all, as it doesn't deal with domain objects. It's a glorified query tool.
I know, I'm quibbling. This code is functional and it works, doesn't it? It's also just enough of a mess that my LLM is going to try and work around it in the future, creating more of a mess.
Yes, But
Yeah, I know: I don't like the Repository pattern. I'm a data person, and I find that using a repo together with a modern data access tool is not only overkill, it makes you do silly things with data (like passing an open transaction between layers of your application).
You could, however, convince me I'm wrong. Not only that, but you could show me (and others) how your LLM actually figured this out in such an elegant way, that it blew your dang mind!
This, friends, is why I do my cohorts. It's one thing to have an opinion based your experience, it's another to test that opinion with other people. You can open their minds, they can open yours.
If you're interested in joining the summer one, just click that link above. If not, I have a whole site dedicated to discussing things like that, and I would love to have you join us!
Patterns, They Matter Still
Software patterns and design principles still matter, and, in fact, I would offer they matter more than ever. Our understanding of them is also becoming more and more important as these LLMs create more and more code for us.
Appilcations will change, and we need to build for that. Swapping out pieces, upgrading, refactoring, and better tests - these are things we've known for a long, long time. I will admit that sometimes I lacked the vigor and discipline over the years, but now that Claude is writing so much code for me, it's easier than ever to create something amazing.
Watch this YouTube video here to see what I mean. These tools are so powerful, and we're only now scratching the surface.