Could someone show me what a shared helper would look like in this case? This code looks easily readable to me and I fear abstracting it will just make it harder to reason about. Is it just variable_with_a_better_name = that conditional?
Write code like a human will maintain it
91–100 of 325 posts
Re: Write code like a human will maintain it
#92There 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.
Yeah, agreed. These have started popping up a lot more recently, where I get a 5 sentence paragraph explaining how function overloading works in c++.
Re: Write code like a human will maintain it
#93Write 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 good experience with using open-code-review:
* https://github.com/alibaba/open-code-review
** https://layandreas.github.io/personal-blog/posts/beyond-vide...
Re: Write code like a human will maintain it
#94Counterpoint: 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.
Re: Write code like a human will maintain it
#95In a similar vein, here's my favorite prompt: "Please review the tests you've written. Will the tests actually test what they're meant to? If the code breaks, will the test fail?" It's amazing how often LLMs will write tests that don't test anything.
Re: Write code like a human will maintain it
#96We still need to discuss this things for real? Aren't they already taken for granted after all this "experimenting" with LLMs? I'm wondering when we will discuss hand coding again without treating it like a taboo anymore. LLMs can be useful in so many ways it's tiring knowing people are delegating the entire source code typing to agents, to me it's like hearing from people that the web is good and we should be happy with it
Re: Write code like a human will maintain it
#97I 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. Claude tends to leave comments like “button click causes save now, no longer uses onBlur” when the code really never used onBlur, that was just a thing Claude wanted to do earlier in the same task/branch and I redirected it at some point.
Re: Write code like a human will maintain it
#98So the new prompt is "Write code like a human will maintain it" ?
Re: Write code like a human will maintain it
#99Write code like a human will maintain it — and that human is you at 3am six months from now, fueled by regret and cold coffee.
Re: Write code like a human will maintain it
#100There 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 overall goals. Then break it down into routines and order of operations, all still in plain english. Once I was happy with that, I'd break up the comments with blocks of code. I guess this is sort of like "literate programming" though I was doing it long before I ever heard that term and I still have never read much about it. It's almost more like I was prompting myself towards the end goal. The downside of this approach is that the comments do end up more or less just explaining in english what the code is doing, so maybe aren't quite as useful to future maintainers.