Write Code Like a Human Will Maintain It, Not Just for AI

Crazy how many engineers in here just say they are using another prompt on top. From my experience that makes things worse. It does abstractions, but the wrong ones. It overcomments, confusing future calls of the LLM.

To me building on multiple scalable systems this has been the most dangerous part of LLMs. On a good codebase it will work good, but it will maek it worse, so you keep using it, till it doesnt work and then you have to pay the bill and fix for what you didn’t build before.

If you put an agent on a fresh codebase 2 things are often given:

-> You have a mental model of the code

-> The code is somewhet concise

After multiple iterations both is lost and LLM performance degrades. To solve this you can regular refactor, but it’s not a nice experienc. So my best solution is:

I use LLMs for exploration and for review, but I write the code myself. I find it hard to believe why so many engineers try to avoid it. It’s not consuming much of my time. And it’s actually the most enjoyable part.

Sometimes I race AI i give it a prompt /bug to fix and at the sametime im greping/symboling through the codebase and tryto fix it myself. AI isn’t always faster.

Wild idea: just write code.

I know. It’s an unbelievable concept in this AI era. Write code? Isn’t that what dinosaurs did?

If you expect that a human will need to read and maintain that code you might as well write it for them. You’ll get annoyed by having to read overly-verbose copy-pasted code. So will they. So write the code yourself and bringo: you’ll fix things yourself and write things in a way that makes sense for other humans to maintain.

Or you can come up with a convoluted web of markdown files to try and coax your agents and loops to understand what future human maintainers will expect the code to look like.

I’m not sure what path will be easier in the long run. Anyone inherit a loop-based agent-driven code base yet and have to try to understand it?

I have good results with this prompt after every larger change: Now do a final code check. Is everything tidy and do the components adhere to the principle of separations-of-concerns. Is everything in an understandable and maintainable state? Do we make any assumptions that may not be true anymore? Is any code left over from previous edits or experiments that does not belong into the codebase? Is the documentation still representing the current state of code?

> The next time you ask the LLM for another endpoint with the same access rules, the model won't start from first principles. It'll start from the other four copies already sitting in your repo.

To be honest I'm not sure how true this is. I think it's more that there does seem to be quite a baked-in bias to repeat basic structures and not reuse (much less come up with) abstractions. So where that is the existing pattern it looks like it's keeping with that, when in reality it would often do that either way.

There have been many cases where I've started a piece of work by laying down very rigid abstractions and a few examples of using them, and I explicitly prompt to not only exclusively use the specific abstraction API but also copy the way I've used it. And the (frontier) LLM does neither, it just steams ahead re-implementing things from scratch from bottom up basic structures, partially and often totally ignoring the abstractions.

I don't know exactly why this should be the case but my naive suspicion is that there's just an awful lot of this type of stuff in the masses of training code and the weights just somehow 'know better' how to get results this way, rather than using your more novel abstractions/patterns.

There is an old quote:

"Add comments to your code under the assumption that the next person to maintain it is a homicidal maniac who knows where you live"

In a similar vein, here's my favorite prompt: "Please review the tests you've written. Will the tests actually test what they're meant to? If the code breaks, will the test fail?" It's amazing how often LLMs will write tests that don't test anything.

We still need to discuss this things for real? Aren't they already taken for granted after all this "experimenting" with LLMs? I'm wondering when we will discuss hand coding again without treating it like a taboo anymore. LLMs can be useful in so many ways it's tiring knowing people are delegating the entire source code typing to agents, to me it's like hearing from people that the web is good and we should be happy with it

I continually run codebases through different models to have them look for bad code smells like repeated code. That's been pretty effective. You do have to maintain over time or else you end up with a sloppy mess which I can only imagine compounds.

I've seen lots of code that people have maintained for 20 years and its full of these duplication and worse.

In fact I'm sad to say that majority of code I've seen people write and maintain is worse than what LLMs produce today.

Often it is inexperience, sometimes it is willful negligence, but most often it is just tight deadlines and pressure to do finish whatever is being done right now. People know how to do it better, but nobody got the time and budget to actually do it.

LLMs also learned from that.