alt Hacker NewsA 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.
Replies
Mine says what I tell engineers:
> Write in-code comments that describe _why_ code or a class does what it does, but not _what_ it does. The "what" should be self-evident.
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.
I would never tell an agent to write "what does the code do" comments. Their default comments are already way too fluffy.
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".
> 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...
My biggest pet peeve with agents is when people beg their (non-deterministic) agents to do something that a lint rule could've accomplished
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.
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.