Write code like a human will maintain it • Hacker News Board

Re: Write code like a human will maintain it

#261

Post by mulmboy » Fri, Jul 10, 2026, 8:42 PM UTC

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.

There's a cluster of issues like comments like "use a set instead of ..." after changing something which will just confuse people in the future. Or comments referring to irrelevant details of the planning/implementation process.

It's as though the machine can't separate the chat and planning docs from the code itself and so they meld into each other. As though it can't fully grasp that the code will outlive the current session by years.

Anyway I find a checklist approach works well to sort this out. I don't consider looking at machine generated code until after a checklist covering all this sort of stuff has been applied. My checklist approach currently has about 50 items which I have the machine apply by splitting it up across about 20 subagents. Pretty silly but it seriously improves the first-pass quality vs only a few subagents. I find this checklist can effectively eliminate words like "genuine" and "landed" from the code too. Eliminates vague and made up terminology. Makes it less nauseating

Re: Write code like a human will maintain it

#262

Post by footydude » Fri, Jul 10, 2026, 8:45 PM UTC

hoppp wrote: post #141

el_io wrote: post #88

Earlier quoted context omitted.

Cat is out of the bag. Other than recreational programming I doubt many will write code without any form of LLM.

If everyone is using LLMs then nobody has advantage In that case, humans with superior skills who can write code become the advantage. That is important for companies that compete with each other.

> If everyone is using LLMs then nobody has advantage

LLMs are a tool like any other - and like any tool there will be people who are better at utilising the tool to achieve an outcome than other users of the tool.

Those differences typically come down to a combination of experience, in-depth understanding of your subject/objective and an awareness of the strengths and weaknesses of the tool.

TBH the rise of LLMs reminds me a lot of the era when google search emerged. People's ability to utilise a search engine to achieve their aims was massively varied.

* Some people were absolutely useless - they struggled to use a search engine to find anything beyond the most basic of things.

* Others were ok - they'd be able to dig a little deeper, they knew a few of the tricks of the searching trade and they had a bit of an understanding of where to look/how to look for something obscure.

* Some were good - they knew all the key search constraints, they had a good understanding around how data is structured and what keywords and approaches to use when to get to the thing they need

* and some had 'google fu' - those people seemed to have a god-like ability to navigate the internet to find the most obscure things in a matter of seconds.

LLMs are different to search engines but their rise shares many similarities to them - they are changing the rules of the game in a monumental way; they have fundamentally reduced the barriers to entry in many fields.

The skills that made someone valuable in a pre LLM world do still matter, but IMO we're currently starting to go through a major change where the people who learn how to best utilise LLMs within their field will find themselves leapfrogging people with stronger skills who obstinately seek to avoid using the new tools becoming available to them.

Re: Write code like a human will maintain it

#263

Post by ryanmcbride » Fri, Jul 10, 2026, 8:59 PM UTC

__jonas wrote: post #235

overgard wrote: post #220

Earlier quoted context omitted.

My experience is the more things you add to the list, the worse agents perform (I'm not exactly the first person to notice this) I actually have a pretty simple set of instructions right now and Claude still regularly messes them up. Like, my first instructions are: - Never commit to git without permission. - Never sign commit messages You know what it constantly does? Commits without permissions and signs commit mes…

I’m not a Claude code user, is there really no way to get it to not commit to git other than “asking it nicely in a prompt”? I thought there was some sort of permission system?

I never ran into it making commits before but when I tried Fable it made a bunch of commits signed by Claude, but then in the next prompt I just said "don't make commits anymore" and it was like "okay" and saved its own little md file and it hasn't happened sense.

I want to be clear that I'm not saying this to discredit the people saying they can't get claude to stop making its own commits, I'm just adding data to the "wow this is inconsistent" collection.

Re: Write code like a human will maintain it

#264

Post by exalt72 » Fri, Jul 10, 2026, 9:17 PM UTC

hoppp wrote: post #141

el_io wrote: post #88

Earlier quoted context omitted.

Cat is out of the bag. Other than recreational programming I doubt many will write code without any form of LLM.

If everyone is using LLMs then nobody has advantage In that case, humans with superior skills who can write code become the advantage. That is important for companies that compete with each other.

[dead]

Re: Write code like a human will maintain it

#265

Post by throwaway27448 » Fri, Jul 10, 2026, 9:22 PM UTC

hoppp wrote: post #141

el_io wrote: post #88

Earlier quoted context omitted.

Cat is out of the bag. Other than recreational programming I doubt many will write code without any form of LLM.

If everyone is using LLMs then nobody has advantage In that case, humans with superior skills who can write code become the advantage. That is important for companies that compete with each other.

> If everyone is using LLMs then nobody has advantage

People with more capital will always have an advantage. This is a large part why the american market fails to produce convincing competition.

Re: Write code like a human will maintain it

#266

Post by munificent » Fri, Jul 10, 2026, 9:24 PM UTC

0x457 wrote: post #258

overgard wrote: post #220

Earlier quoted context omitted.

My experience is the more things you add to the list, the worse agents perform (I'm not exactly the first person to notice this) I actually have a pretty simple set of instructions right now and Claude still regularly messes them up. Like, my first instructions are: - Never commit to git without permission. - Never sign commit messages You know what it constantly does? Commits without permissions and signs commit mes…

I do the opposite. I force LLM to "do jj new -m " after every logical batch of edits. No signing is easy - make signing interactive and requiring a password. Anyway, telling agent to NOT do something is always worse than telling agent to do something. That's why you should say something like "Use constants instead of magic strings/numbers" rather than "Do not use magic strings/numbers". Also whatever review its doing…

> Anyway, telling agent to NOT do something is always worse than telling agent to do something.

> That's why you should say something like "Use constants instead of magic strings/numbers" rather than "Do not use magic strings/numbers".

Pro tip: This is good guidance for communicating with humans as well. Don't just block people but give them a path forward. (But don't force them down that path, because people really hate feeling like their agency is being impinged.)

Re: Write code like a human will maintain it

#267

Post by Iakeman » Fri, Jul 10, 2026, 9:32 PM UTC

overgard wrote: post #220

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

My experience is the more things you add to the list, the worse agents perform (I'm not exactly the first person to notice this) I actually have a pretty simple set of instructions right now and Claude still regularly messes them up. Like, my first instructions are: - Never commit to git without permission. - Never sign commit messages You know what it constantly does? Commits without permissions and signs commit mes…

The commit signatures are a setting, you have to disable it in config

Re: Write code like a human will maintain it

#268

Post by Jarwain » Fri, Jul 10, 2026, 9:34 PM UTC

overgard wrote: post #220

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

My experience is the more things you add to the list, the worse agents perform (I'm not exactly the first person to notice this) I actually have a pretty simple set of instructions right now and Claude still regularly messes them up. Like, my first instructions are: - Never commit to git without permission. - Never sign commit messages You know what it constantly does? Commits without permissions and signs commit mes…

I have dedicated checkpoint and commit skills. Checkpoint has it run my review skill, then run my commit skill. The commit skill just asks it to suggest commit messages for my review. Having these skills in place has resulted in claude preferring to use the commit skill instead of committing on its own, and suggesting commit messages to me before actually doing the commit.

Re: Write code like a human will maintain it

#269

Post by secondcupofchai » Fri, Jul 10, 2026, 9:34 PM UTC

I think we have to accept the innovation, adapt to new reality and use it to our advantage, my 2 cents on this.

Re: Write code like a human will maintain it

#270

Post by chickensong » Fri, Jul 10, 2026, 9:38 PM UTC

overgard wrote: post #220

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

My experience is the more things you add to the list, the worse agents perform (I'm not exactly the first person to notice this) I actually have a pretty simple set of instructions right now and Claude still regularly messes them up. Like, my first instructions are: - Never commit to git without permission. - Never sign commit messages You know what it constantly does? Commits without permissions and signs commit mes…

Use hooks.