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

101–110 of 325 posts

Re: Write code like a human will maintain it

#101

Post by hollowturtle »

uhhhd wrote: post #94

Counterpoint: This no longer matters because we are not going back to hand-writing these functions. These patterns were designed to make code easier for humans to read and write, but that is no longer the primary way software is built.

Counterpoint: as long as context don't rot or it's less effective that starts maintaining repetitions only slightly different. Also

> we are not going back to hand-writing these functions

do you really think there isn't a good chunk, if not the majority outside some bubbles, of developers that still hand code? Crazy to hear, I bet you're not a programmer

Re: Write code like a human will maintain it

#102

Post by fphilipe »

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.

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 my preferences it then deletes most of them or improves them.

Today I asked Claude why it disrespects my preference and it said that the surrounding code was like that and it followed that style. It suggested I add this line to my global CLAUDE.md file:

> The comment rule above beats the style of the surrounding code: neighboring files with what-style comments are not license to write more of them, and comments carried along when porting or copying code must be re-judged against the rule, not kept for consistency.

Let's see if that improves things.

Re: Write code like a human will maintain it

#103

Post by internet101010 »

No. I will generate code in a way that makes it easier for clankers to maintain it, because they will actually be doing the maintaining. In practice, this means that most of my time is dedicated to improving the repo harness because the state of the repo harness directly determines the quality of the codebase as a whole.

At a minimum, there should be precommit checks and CI workflows that cause PRs to fail if the documentation is not up-to-date and synced with the other docs.

Then regular codebase analysis for improvement. This is where you find the bug sources, make new modules for consolidation, and get those +5000/-4000 PRs that people stuck in the world of manual code review hate.

Re: Write code like a human will maintain it

#104

Post by Ancalagon »

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…

Just pull the slot machine lever

Re: Write code like a human will maintain it

#105

Post by dugmartin »

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

I have my own review skill (I think it predates when Claude added theirs) and one thing I'd add to your description is tell it to examine all the code and then, based on the changes, do a multi-role review of the code again using the most appropriate N of the following roles based on the changes: ... (where ... is a long list I have like Senior Engineer, Security Engineer, WCAG specialist, etc). Claude will spawn those reviews in parallel and then consolidate the feedback. I do spec based development so I just have my skill append the issues to the spec so I have a trail of issues and decisions.

Re: Write code like a human will maintain it

#106

Post by geraldwhen »

saghm wrote: post #52
schnebbau wrote: post #7

That sounds like a good idea, but shipping 10x as many features and bugfixes sounds better. I started using AI with the best intentions. Checking everything before committing. Improving output by hand if it didn't quite follow the existing code style guidelines or variables were not named as well as they should be. Or if it did something sloppy or hacky. Now, AI GOES BURRRRRRRRRRRR! If the tests pass it's good to shi…

How did you know you're not stuck at a local optimum where the AI could iterate even faster if you enforced higher quality on what it produced? To make up some hypothetical numbers in order to illustrate with math: if you ship bugfixes 10x faster but then have 11x more bugs you need to fix, that's not a net improvement. Even if it's only 5x more bugs, maybe you could reduce that to 2x if you changed how you worked to…

It’s a new form of development. The thing that the author didn’t state is that to work the code base at all, you must also use these tools and workflows.

Manual edits literally aren’t possible. You can’t grok the code growth and the new patterns fast enough to be productive.

This does work. I’ve seen it in real products. Nobody has a real mental model of the code flows. But with enough money in Claude credits it doesn’t matter.

The spend to support this development model is something like $50/day/developer.

Re: Write code like a human will maintain it

#107

Post by Espressosaurus »

ebiester wrote: post #51
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:…

You should do an experiment of splitting that up to multiple reviews that are logically together. My hypothesis is that you may be losing signal due to the amount of text expected back.

Yeah. I have a set of 5 review prompts attacking different problems, an adversarial review, and then a final synthesis, with the best results gotten by multiple passes using multiple models (the adversarial review stage combining all passes into one review per model and the synthesis picking the best of the two or three adversarial reviews). Expensive but it actually finds real problems that the single pass reviews rarely seem to find.

Re: Write code like a human will maintain it

#109

Post by rconti »

I have very mixed results with LLMs, but I actually find they're really GOOD at, unprompted, pointing out existing code that is redundant and could be simplified and so on.

Where it really, really struggles for me is in existing complex infra codebases.

Re: Write code like a human will maintain it

#110

Post by discreteevent »

tjwebbnorfolk wrote: post #36
klabb3 wrote: post #8

Earlier quoted context omitted.

Why stop there? If you _use_ handwritten products you’re ngmi. I only use vibe coded operating systems, JavaScript sandboxes, compilers, TLS libraries, databases, rendering engines..

This is cute reductio ad absurdum, but it does nothing to refute the basic point made

There was no point made. You couldn't find a shallower comment. Why are you even bothered to defend it?
Post reply on HN