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:…
Write code like a human will maintain it
251–260 of 325 posts
Re: Write code like a human will maintain it
#252I know. It’s an unbelievable concept in this AI era. Write code? Isn’t that what dinosaurs did?
If you expect that a human will need to read and maintain that code you might as well write it for them. You’ll get annoyed by having to read overly-verbose copy-pasted code. So will they. So write the code yourself and bringo: you’ll fix things yourself and write things in a way that makes sense for other humans to maintain.
Or you can come up with a convoluted web of markdown files to try and coax your agents and loops to understand what future human maintainers will expect the code to look like.
I’m not sure what path will be easier in the long run. Anyone inherit a loop-based agent-driven code base yet and have to try to understand it?
Re: Write code like a human will maintain it
#253Re: Write code like a human will maintain it
#254Write 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:…
Do human developers check for 200 items when they do code review? How long would that take? It's quite clear that AI code review could be better even with some error.
What's easy for human to review is also easy for AI (small code base, small PRs). What's hard for AI is also hard for human, if not more. But the time cost is so different that it's almost a nobrainer to choose AI to code and review, especially considering most software out there is not so critical :)
Re: Write code like a human will maintain it
#255Could 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?
We therefore want to encapsulate the logic of all users being "qualified". I think the best way to realize this is to try to say in as few words as possible what we want. We want the user.toBe.qualified, but we can write that even more efficiently, user.isQualified(), so we can ASK at the top of each API `if !user.isQualified()` and then fail loudly and quickly if so, and then go do something afterwards otherwise. We presumably expect multiple users that will have a property of being qualified, so let's use a class:
```js
class User { constructor(data) { this.isAuthenticated = data.isAuthenticated; this.hasActiveLicense = data.hasActiveLicense; \\ many more details... }
// Now encapsulate the boolean property of being qualified, for all Users, in one place
isQualified() { return (this.isAuthorized && this.hasActiveLicense && this.hasPaidInFull && this.hasAdminPermissions); } }
// Now, we can use our isQualified() property at each of our API guard clause by checking if the user is NOT qualified:
if (!user.isQualified()) { return res.status(403).json({ "error": "Unauthorized access requested."}); }
// Critically, the API guard clause remains identical even if we change the criteria for validation and what it means to be "qualified"
```
There are of course many other ways to solve this problem beyond this approach. For instance, you could export a function called isUserQualified(user) (or more likely userId) then call it somewhat similarly:
```js
if (!isUserQualified(user)) { return res.status(403).send("Error: Unauthorized access requested"); }
```
The other approach I like is to use a factory pattern to build a userSession with function arrow notation. That's really helpful when you are getting raw data back from a database call, say as a JSON object. That would look like this:
```js
const createUserSession = (userData) => { return { ...userData, // here we use the ...notation for convenience but don't trust this as secure) isQualified() { return ( this.isAuthorized && !this.isSuspended ); } }; };
// Then you instantiate a user session from the request like this:
const user = createUserSession(res.session.user); if (!user.isQualified()) { return res.status(403).send("Error: Unauthorized"); }
```
There are actually loads other approaches too, like using class inheritance (define a parent User class and child QualifiedUser class, for instance), or types. I would say that readability here is less a concern than the issue that you have multiple APIs and if you refactor or change the logic for qualified users, now you have to refactor your most sensitive attack surface at multiple points. It's just safer to have that rewrite only happening once, wherever you put it, in my view.
Re: Write code like a human will maintain it
#256Re: Write code like a human will maintain it
#257Write 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 list is like 200 items now Do human developers check for 200 items when they do code review? How long would that take? It's quite clear that AI code review could be better even with some error. What's easy for human to review is also easy for AI (small code base, small PRs). What's hard for AI is also hard for human, if not more. But the time cost is so different that it's almost a nobrainer to choose AI to code…
We (humans) don't do 200 point inspection, but we also don't review every code change in a spherical vacuum without prior knowledge of the project. However, we do check a lot of things.
> What's hard for AI is also hard for human, if not more.
That's just plain wrong. AI straight up suffers with counting things, and I'm not just talking about counting 'r' in strawberry. Some things are easier for AI some are easier for human.
Re: Write code like a human will maintain it
#258Write 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…
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 against the list of checks - must be a fresh context.
Re: Write code like a human will maintain it
#259Crazy 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…
>> AI isn’t always faster It is always faster if you don't care about quality and need to churn out code as fast as possible to close tickets.
Re: Write code like a human will maintain it
#260Earlier quoted context omitted.
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?
There are options, but they're not great. I could ban it from using git, but having access to git logs helps it do work so I don't want to go that far. I could probably ban the subcommand, but as a convenience I do like to be able to ask it to make a commit. (I'm not super attached to this, I frequently commit myself just to avoid these issues). It does tend to write good commit messages, so sometimes I ask it to gen…
This way the agent can read git logs (this is very useful) but cannot commit directly (I don't see any value in this).