A bunch of these should be enforce with linting, that way people who still hand-craft code get the same kind of feedback, e.g. Always use {}, even on a one-line "if" statement. & Keep function names short. Less than 30 characters.

Then this one really is a pattern that creates a lot of churn:

- Add a small, to the point, comment to explain what the block does and why. Use examples when possible. Propose ASCII drawings to explain complete systems.

The what _is_ the code.

▲

figmert 27 minutes ago | parent | next [-]

Right. I've really struggling to get AI to stop explaining the what. It seems to add it to the commits, PRs, code, wherever it feels like. I've put in multiple places to not write the "what", but the "why", and in multiple ways, but it still does it in one or other place.

	▲	jaggederest 3 minutes ago \| parent [-]
		The best way I've found to solve this is using LLM as CI - use a small cheap model to inspect the diff and look for those kinds of comments. Prompt left to the observer but using `claude -p` / `codex exec` gets you a lot cleaner output usually, and makes robots fight robots instead of you constantly having to reprompt and it ignoring you.

▲

getnormality 3 hours ago | parent | prev | next [-]

I would never tell an agent to write "what does the code do" comments. Their default comments are already way too fluffy.

▲

saghm 6 minutes ago | parent | next [-]

But then you don't know about where the load bearing seams are!

▲

rustystump an hour ago | parent | prev | next [-]

I added to the memory, system prompts, and the prompt itself and every soa model still litters code with the most inane useless crap. I will then get code to review from a coworker using fable/opus. It has more lines of comments then code.

Maybe I am some god tier code reader (i am not) but i dont think i have ever found a comment in code to be useful in my day job. That isnt true, i once came across

// submit to the dark lord

Above the function that sent a payment to PayPal for processing. It made me laugh so I let it be.

	▲	danielheath 22 minutes ago \| parent [-]
		Most useful code comment I have encountered read: “”” After you give up on trying to refactor this code, increment the following line accordingly. HOURS_WASTED_HERE=26 “””

▲

2 hours ago | parent | prev [-]

[deleted]

▲

hawk_ 13 minutes ago | parent | prev | next [-]

I forbid my agents from adding any comments. I review the code and add comments manually. If I can't understand something despite having the context then I throw away the code instead of having an LLM generate comments to explain what it did. This way the code stays readable/debuggable by humans.

▲

arialdomartini 12 minutes ago | parent | prev | next [-]

Incidentally, I'm from the opposite school and consider every “if” followed by a braced block a smell. If a conditional body needs a block, it's doing enough to deserve a name, so I promote it to a single named call, à la "Extract till you drop".

▲

0xfeba 13 minutes ago | parent | prev | next [-]

> Propose ASCII drawings to explain complete systems.

LLMs are very bad at ASCII drawings.

https://medium.com/data-science/why-llms-suck-at-ascii-art-a...

▲

culi 34 minutes ago | parent | prev | next [-]

My biggest pet peeve with agents is when people beg their (non-deterministic) agents to do something that a lint rule could've accomplished

	▲	irishcoffee 24 minutes ago \| parent [-]
		Seems like 80% of agent use boils down to: grep \| sed -i Which is kind of cool if you’re unaware enough to know to do it yourself. Oh, and find. Agents use find a lot.

▲

_boffin_ 20 minutes ago | parent | prev [-]

One thing I don’t get with a lot of these agents.md and other skills are… why not throw as much mechanical checks and other stuff at the repo to constrain as you want instead of asking a non-deterministic agent (squishy or non-squishy) to maintain it.

With the mechanical routes, we get checks, failures, and so much more. A bit wild to me.

Make an agent operate within defined constraints and yell at it when it doesn’t.