Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Write code like a human will maintain it

unstack.io

Post reply on HN
Print view View original

131–140 of 325 posts

Re: Write code like a human will maintain it

#131

Post by hakunin »

I have been on a quest to get AI to code like me, using pi harness, and any model that it can support. I'm mostly a Ruby programmer, so here's my journey so far.

1. Created a "coding" skill with every practice I posted on my blog website, as well as a bunch I had in the queue to blog about but never got a chance, summarized into "do this" kind of language. This is more or less good for any PL, but a bit Ruby-slanted.

2. Created a "rails" skill because that's my framework, where similarly I explained my approach to architecting Rails apps.

3. Created a "writing" skill where I literally fed it my entire blog, and tried to get it to write more like me (mixed success, weaker models did better for some reason, but I haven't tried the GPT-5.6 series yet).

4. Next, I really wanted it to format code exactly like I would, even things like "let's make this `if` into a ternary, let's split these assignment groups with a line break, let's vertically align here, but not there", but with GPT-5.5 (my primary driver up until yesterday) there's almost no way to make a skill of reasonable size that will be consistently applied. So instead I instructed the agent to write me a Rubocop cop for every single situation I ever encounter where I would've formatted code slightly differently. This was quite powerful, because I usually thought of linters as enforcers of objective consistency decisions in the codebase, but this was me going full format nazi on the agent. And the nice part is that these cops can contain some non-autocorrectable feedback, which AI will follow.

5. I'm working on a review loop where the most easily missed parts above get double checked. This is the first thing I'm doing with pi subagents. (I feel like I'm getting better results if I don't use subagents for code exploration, other tool calls). The idea here is that I want reviews to be in the implementation loop. I always read/review code in the end, but so want it to have gone through the review loop before it gets to me. Since implementation is already context-heavy, I want to be able to orchestrate this loop without adding to the implementation context.

6. I'm also adjusting all of the above for GPT-5.6, because it requires less guidance, so I'm carefully trimming the verbiage to save tokens.

So far the results have been surprisingly good. I want to experiment with GLM-5.2 running under these constraints.

One invariant in all of this: I read the code. My end product is not working software, it's good code (which also incidentally produces working software).

Re: Write code like a human will maintain it

#132

Post by bluGill »

sejje wrote: post #73
carimura wrote: post #19

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.

Do you think it matters that it's a different model? Or is it more about the review process and a context reset?

I have personally not found value in a different model. The review itself often is good.

Re: Write code like a human will maintain it

#133

Post by soperj »

cadamsdotcom wrote: post #29

Write yourself a /review command. That is an empty markdown file at `.claude/commands/review.md`. In it, put a checklist of things the agent should look for. When you’re ready to have your agent review the code, type `/review`. The checklist will be examined and it’ll plan out some findings to ask you if you want them fixed. Mine starts with “Enter plan mode. Examine the differences on this branch vs. main. Consider:…

Why wouldn't it already just do this though?

Re: Write code like a human will maintain it

#134

Post by mnicky »

Benjammer wrote: post #97
planb wrote: post #64

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 st…

I usually just say “make sure this code is professional and ready to deliver as a senior engineer” and it usually infers all that stuff you said plus more things as well. I try to give it the goal and let it decide what to do. One thing I usually keep having to point out directly is to remove all “progress tracking” code comments and make sure all comments are appropriate for long term maintenance in the code base. C…

For things the agent forgets to obey often, at least in Claude Code, there are also "output styles" that are more deeply embedded - into a system prompt - and agent is also periodically reminded of them during the session: https://code.claude.com/docs/en/output-styles

I haven't used them so far but maybe these would work better than basic instructions for such cases.

Re: Write code like a human will maintain it

#136

Post by __MatrixMan__ »

> Who cares about DRY? You don't have to be the one updating the same long conditional in four different files - the AI will just do it for you! Right?

One pattern I've really been enjoying lately has to do with a language called haxe. It's designed to be compiled into other languages (java, python, others). There's this extension called reflaxe which lets you make mini compilers for compiling haxe into pretty much anything.

So if I have anything with duplicate structure... like maybe I want the CLI subcommands to resemble the http API.

    $ foo bar --baz 6 # produces similar output as HTTP GET /foo/bar?baz=6
...and `docs/generated/foo.md#bar` should have documents both the CLI and the http usage. Then I have the LLM maintain a haxe source of truth and then have it compile that source of truth to the other stuff.

Previously I was using OpenAPI spec's and generators for this, but they wound up feeling like a black box that I ended up debugging all the time. The reflaxe setup is much more generic. So you end up with this mountain of generated code, but unlike LLM-generated code it's obviously generated (in .../generated/thingy.py or whatever) and a comment at the top of the file says where to look to learn how it's generated). I'm generating docs this way, accessor functions for database tables and SQL for making those tables, matching clients and servers in different languages... it replaces a lot of purpose built tools with just one, and LLMs are pretty good at it.

So even though the repo is large, the parts of it that are authoritative remain small. I find LLM's manage this boundary much better because it's so crisp an in their face. But they have to be told to do this, otherwise they'll just create context-size problems that they'll later struggle with.

Of course you could do this with yaml files or some such, but unlike yaml, haxe has a type system, you can write tests in it, so the agent can notice fundamental flaws before the generation happens... with yaml those flaws would be propagated into the generated code before they'd get noticed.

Re: Write code like a human will maintain it

#137

Post by dionian »

alexpotato wrote: post #3

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"

sounds like a recipe for over-commenting. The code should be self-documenting. Comments are for the places where there are dragons.

Re: Write code like a human will maintain it

#138

Post by notatoad »

soperj wrote: post #133
cadamsdotcom wrote: post #29

Write yourself a /review command. That is an empty markdown file at `.claude/commands/review.md`. In it, put a checklist of things the agent should look for. When you’re ready to have your agent review the code, type `/review`. The checklist will be examined and it’ll plan out some findings to ask you if you want them fixed. Mine starts with “Enter plan mode. Examine the differences on this branch vs. main. Consider:…

Why wouldn't it already just do this though?

It does. Claude has a built in review and it’s pretty good. But it doesn’t know exactly what you want. This is a way to tell it.

Good way to double your token use though, if you’re concerned about that.

Re: Write code like a human will maintain it

#139

Post by hoppp »

danielbln wrote: post #89
Snoopfrogg wrote: post #75

Or we start writing code without LLMs.

No one is stopping you. It's only if you want someone to pay you for hand writing code that you might feel a certain competitive pressure that makes it economically difficult, let's say.

One reason to write by hand is to have intellectual property, since it was ruled that AI generated code is in the public domain by default, so licensing is hard.

Another thing is competitive edge, if you use claude and your competitors use claude then nothing really gives you an edge. AI is a commodity, not competitive edge.

The competitive pressure should drive human work because it's unique.

Re: Write code like a human will maintain it

#140

Post by actionfromafar »

TimTheTinker wrote: post #71
alexpotato wrote: post #3

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"

Right now the comments that upset me the most are LLM TMI-style comments that break encapsulation by talking about the behavior of specific current callers of a function right above the function definition . I recently reacted angrily in a PR review comment after encountering one for the umpteenth time... that caught me off guard. I didn't know I was capable of that.

Well, on the one hand, Hyrum's Law: "With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviors of your system will be depended on by somebody."

so that can be useful information in some situations.

On the other hand, what a horrible out of date mess of comment that can turn out to be a little bit later. Taken as gospel by the next entity (human or llm) to massage that function.

Post reply on HN