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

161–170 of 325 posts

Re: Write code like a human will maintain it

#161

Post by hakunin »

SoftTalker wrote: post #100
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"

Used to work with a guy who would frequently say "a comment is an apology" i.e. the comment is there because the code itself is not clear. That can be the case, but I generally find more comments better than fewer, especially if they relate the code to actual business or functional requirements and don't just restate what the code is doing. Years ago I would often write comments first. I.e. start with describing the…

There was a phase, which I also got sucked into at the time, that comments are bad. Problem is, to make your code be so self-explanatory that it conveys business decisions, background stories for how you've arrived here, research-based choices made, you would have to name your variables and functions in a batshit_insane_way_that_obfuscates_behavior_among_the_names. It doesn't make anything better.

Use short names where they're contextually clear. Use long names where they're contextually weird/non-belonging. Use comments to explain the "whys" of your code.

Re: Write code like a human will maintain it

#162

Post by jhghbj »

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

[dead]

Re: Write code like a human will maintain it

#163

Post by metalspot »

code review is a dead end. the only way building with AI makes sense is in secure systems that can run unaudited code.

code review has always been a liability fig leaf. it is much harder to understand a system from reading the code than writing the code. if AI can write code 100X faster than humans it is simply impossible for humans to do real code review. effectively it is just pretending to do code review, and then running unaudited code without the proper systemic security guardrails in place.

Re: Write code like a human will maintain it

#164

Post by hoppp »

danielbln wrote: post #157
hoppp wrote: post #153

Earlier quoted context omitted.

That's not always the case imho. Think about advances in running inference, any innovation will happen in the details. Higher layer can stack gpu's but the implementation can still be improved. Often small technical changes like "making a service 5% faster" are worth millions for large companies. That's all implementation.

I don't see why a strong model wouldn't significantly outperform any human in this sort of low level optimization work. We don't hand optimize assembly either.

It's about the competitive edge. If a public model can do it, everyone has access to it so nobody has advantage.

If you want LLMs to be your advantage you can train your own, that's completely valid.

Let's say you want to have a company that runs inference 5% faster, if everyone can do it your business model is worthless.

Re: Write code like a human will maintain it

#165

Post by sheept »

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.

Aren't LLMs trained on and optimized for human code? In general, anything that is concise is more effective as context for the LLM, whether it be your CLAUDE.md or code, since LLMs are meant to model human language.

Re: Write code like a human will maintain it

#166

Post by hungryhobbit »

mnicky wrote: post #134
Benjammer wrote: post #97

Earlier quoted context omitted.

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.

In practice output styles are just more context (equivalent to CLAUDE.md or memory) ... but with a slightly increased weight.

Re: Write code like a human will maintain it

#167

Post by dualvariable »

I think the usable counterpoint here is that you can refrain from excessively DRY'ing code up and defer it until later.

There's a huge cost to Clean-Code-style DRY'ing of your codebase which is that you wind up creating all kinds of little functions that all add cognitive overhead to reading your codebase, and that premature DRY'ing can lead to picking the wrong abstractions.

If you can tolerate a bunch of copypasta, you can sit back after you've written 5,000 or 10,000 lines of code and can look at the actual result, instead of speculating, and make better-informed decisions about how to clean the codebase up. If you're making those decisions the first time you copy a bit of code around, you can wind up making a worse mess, since you often don't know where you're going.

Re: Write code like a human will maintain it

#168

Post by j_bum »

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 drives me nuts as well. I hate also hate when LLMs use plan-document references in comments/doc strings too. “Landed in stage 1…”

I have a lot of CLAUDE.md rules to restrict this stuff, but realize the “encapsulation” language is something I’m missing.

Re: Write code like a human will maintain it

#170

Post by jwpapi »

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.

Post reply on HN