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

121–130 of 325 posts

Re: Write code like a human will maintain it

#121

Post by boredtofears »

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.

I have tried prompting it out and providing strong guidelines in my AGENTS.md against it, but I still get _way_ too many useless "explain the code" style comments no matter how much I try. I usually have to do something like "Look at all commits in the past X days and remove (DO NOT TRIM) all comments that are not truly exceptional"

Normally when I can't get claude to follow a prompt I try a lint hook, but it's tough to lint something that subjective.

Re: Write code like a human will maintain it

#122

Post by baptou12 »

I agree, but “write code like a human will maintain it” can also be limiting: if LLMs reduce the cost of maintaining more explicit or verbose code, we should use that to raise the standard, not preserve compromises made for human convenience.

Re: Write code like a human will maintain it

#123

Post by alexsmirnov »

The problem of duplicated code described in the article, goes in a different way in reality: AI does not update 4 places in the same way, but implement them a slightly different. I found diverged business logic all the time. For example, file upload dialog for a document with the same meaning: in one place, it accepts pdf only. Another allows to upload pdf or docx. The last accepts pdf, doc, docx, and txt.

Re: Write code like a human will maintain it

#124

Post by sejje »

gdulli wrote: post #37
Invictus0 wrote: post #4

[flagged]

People are so desperate for this to be true. Maybe it comes from a subconscious recognition that their own self-imposed deskilling will inevitably catch up with them.

People are so desperate for [GP post] to not be true. Maybe it comes from a subconscious recognition that their own hard-earned skillset will inevitably become obsolete.

[More seriously, the comment you replied to doesn't put out any desperation. It's stated like a fact. It could easily be based on logic & reason, not emotional desperation.]

Re: Write code like a human will maintain it

#125

Post by snarfy »

## HARD RULE - design scope must always be maintained and no function should ever be longer than XXX lines and no class should have more than Y methods. Create new classes and subclasses and refactor until the criteria are met.

You'd be surprised how readable this makes the code when XXX is about the size of your vertical screen and Y is relatively small.

Re: Write code like a human will maintain it

#128

Post by illuminator83 »

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.

Re: Write code like a human will maintain it

#129

Post by mnicky »

fphilipe wrote: post #102
TimTheTinker wrote: post #71

Earlier quoted context omitted.

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.

This is what has been frustrating me most lately. Even though I have a rule in my global CLAUDE.md that says: > Only write comments to explain the why when it is not obvious from the code (rationale, gotchas, constraints). Do not comment on the what — well-named code already says it. Do not comment on how a framework works. It still keeps adding these bad comments. When I then ask it to review the comments based on m…

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

Maybe these would work better for such cases.

Re: Write code like a human will maintain it

#130

Post by bluGill »

baptou12 wrote: post #122

I agree, but “write code like a human will maintain it” can also be limiting: if LLMs reduce the cost of maintaining more explicit or verbose code, we should use that to raise the standard, not preserve compromises made for human convenience.

Will it? Okay, first we need to ask "which humans" - there are many humans who don't see a point in the things we call best practices. I've work with programmers who are faster than me to getting low bug count code out the door, despite writing 70,000 line functions - he didn't understand why nobody else wanted to add new features to his code.

The standards most "good developer" humans demand were learned from many decades of painful experience about what happens when you do it the other way. These are not only compromises for human convenience, they often are things that we have learned will come back to bite you later even though they just add more work today for no gain.

Post reply on HN