20 ms·
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
by OptionOfT 1mo ago
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.
- getnormality 1mo agoI would never tell an agent to write "what does the code do" comments. Their default comments are already way too fluffy.
- deleted 1mo ago[deleted]
- rustystump 1mo agoI 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 1mo agoMost 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 “””
- cwsx 1mo agoI always loved the classic _"Here be dragons"_
- saghm 1mo agoBut then you don't know about where the load bearing seams are!
- JSR_FDED 1mo agoHonestly? That’s the kicker.
- throwatdem12311 1mo agoI tell the agent to NEVER write comments in the system prompt and it ignore it like 90% of the time. RLHF is a helluva drug.
- bombcar 1mo agoWe trained agents on millions of pages of documentation telling them to write good comments and good code and then we tell them never to write any comments. It’s almost the “we built a robot who loves to play Sonatas and gave it no hands” type of thing.
- benregenspan 1mo agoBeing overly trained on comments in documentation could be one of the reasons why Claude models write frustrating comments (which often manifest as written justifications of how the code satisfies the prompt). A comment in a tutorial is going to be geared to explaining how the code relates back to the tutorial task or restating what the code does, rather than documenting the "why" of surprising code.
- embedding-shape 1mo agoWhat models are you using? I've had "Never add any new code comments" in my system prompts for like a year at this point, seems every model above 14B picks this up just fine. Are you using llama 7b or similar for testing this?
- throwatdem12311 1mo agoPretty much Opus 5 exclusively.
- telotortium 1mo agoHmm, I guess everyone here is using Claude? I find that Sol is much more restrained, to the point where I have a prompt to tell it to add short comments for things that are not obvious. Really, I find the verbosity problem to be worse in tests. I regularly prompt my review agent to remove tests used only for scaffolding to write the code in the first place. The agent is in a way following strict TDD, which reminds me why I don’t like TDD, even though some of the generated tests can be useful.
- sampullman 1mo agoSol adds comments when I use it, but it's not nearly as verbose as Opus 5/Fable. For the latter I'll often include an example of a comment it wrote, along with my own rephrasing, and tell it that "future readers will understand code context; good naming is the best documentation". This works alright if I include in the actual prompt, but annoyingly it often doesn't in CLAUDE.md or memory.
- culi 1mo agoMy biggest pet peeve with agents is when people beg their (non-deterministic) agents to do something that a lint rule could've accomplished
- irishcoffee 1mo agoSeems 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.
- eterm 1mo agoSo it turns out that a lot of these unix utilities have such bad UX that having a tool that knows how to really leverage them feels like a superpower. If you've ever used an LLM to deal with ffmpeg you'll know exactly what I mean.
- drfloyd51 1mo agoIt is incredibly difficult to make an UX that can beat simply typing what you need in your own words. You think of what you need, and you type it. No need to even ask “what options should I use?”
- skydhash 1mo agoI would rather bet that people don’t know that their problem has been solved for ages. Either they don’t know about the tools or can’t make the leap to think of using something like awk or sed to quickly script out their use cases. Or even quickly draft up a quick function/plugin in something like vim, emacs, sublime,… In “The Pragmatic Programmer”, the power of unix tools and editor fluency is well argued. There are plenty of other books like “Unix Power Tools”, “Small, Sharp Software Tools”,…
- bombcar 1mo agoMy problem is always the time necessary to get good at the tool is slightly more than just brute forcing it one more time.
- figmert 1mo agoRight. 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 1mo agoThe 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.
- 5thaccount 1mo agoI've reached that point as well. Is there a preferred model and prompt you use for that?
- jaggederest 1mo ago[flagged]
- _boffin_ 1mo agoOne 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.
- hawk_ 1mo agoI 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.
- lkjdsklf 1mo agoThat seems like a really smart workflow I wish my coworkers would adopt this. I’m sick of reading a fucking Charles dickens novel for every fucking tiny function
- Mtinie 1mo ago[flagged]
- jamesfinlayson 1mo agoUgh, this. Had a workmate recently churn out 4,000 lines of code using Claude and I'm sure half of it was just comments.
- robby_w_g 1mo agoHow do you stop LLMs from making comments? In my experience, LLMs treat requirements for code output as suggestions
- deleted 1mo ago[deleted]
- miki_oomiri 1mo agoAsk the agent to write a script to run after each changes, against the newly added code. Use that script as a super linter. That’s the only way I found to strictly enforce some rules, like the no comments rule, without enforcing them against my own changes or old code.
- 1mo ago
- 0xfeba 1mo ago> 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-a9516cb880d5 https://medium.com/data-science/why-llms-suck-at-ascii-art-a...
- throwuxiytayq 1mo ago[dead]
- dolmen 1mo agoThis article is dated January 2025. Labs have now long understood that ASCII drawing is a core skill needed for coding agents. However, I would not trust them understanding what an existing drawing means, unless it has generated itself.
- arialdomartini 1mo agoIncidentally, 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".
- AdieuToLogic 1mo agoAnother phrase for this is "functional decomposition", which usually is a good thing. Better yet is to identify conditional execution paths as early as possible in order to obviate conditionals in the call tree. For example, identifying a "create a new something" verses an "update an existing something" based on the workflow initially invoked greatly simplifies service and/or persistent store logic.
- what 1mo agoSo you’ll make a two line function to replace a braced block? Seems kind of unhinged.
- arialdomartini 1mo agoIt may happen. I guess you agree that most of the times conditional blocks exist they are more than 2 lines.
- farlight 1mo agoThe "Uncle Bob" school of thought follows this pattern. Look at his projects, I personally find them unreadable. https://github.com/unclebob/fitnesse https://github.com/unclebob/fitnesse
- tyre 1mo agoMine 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.
- throwatdem12311 1mo agoLinters and static analysis -> setup as hooks in your harness. Don’t rely on CLAUDE.md because it’ll ignore it a lot. > ASCII drawings in code Please don’t this is super obnoxious. Make proper diagrams and kee them in knowledge base. Link out to them if you need to and let the agent fetch them via MCP or API or whatever if it wants them.
- skydhash 1mo ago> The what _is_ the code. Even the why sometimes shouldn’t be a comment, unless it’s very immediate to the code itself. What’s often more necessary is a high level overview of the design of the solution, because that’s what drives the design of the code and link disparate section. Especially the glossary , which you let you understand the name of the symbols (variables, struct. functions,…) used in the code. It’s like learning the culture associated to a foreign language instead of trying to translate each single word with a dictionary.
- vunderba 1mo ago> A bunch of these should be enforce with linting Agreed. One of the first rules I toss into Biome is `noNestedTernary` - LLMs seem to adore completely unreadable nested expressions.
- deleted 1mo ago[deleted]
- duttish 1mo agoThe cost of custom linters has like any other code dropped through the floor. I'm sprinkling all kinds of linters over my latest projects. It seems some people are still sleeping on this, expecting great code from the agents. They're fast and deterministic and I run them in git pre-commit.
- embedding-shape 1mo ago> expecting great code from the agents Yeah, I'm not sure what people are thinking. I keep reading stuff from folks like "I wish models had more common sense" and "I wish they wrote better code", not realizing this is 100% in your own hands, always been. There is no such thing as "clean code" that every programmer agrees on, you have your own subjective opinion and "good" taste about the code, instruct the models to follow it! And automate it while you're on it.
- DenisM 1mo ago> They're fast and deterministic and I run them in git pre-commit. Isnt that too late? I would want the agent to stumble into this as early as possible in the agentic loop, eg at the same time as compiler.
- duttish 1mo agoIt's been working quite well so far and I don't know of any way of hooking custom linters into cargo so they run after compilation. But that's a pretty good idea, wonder if there is a way...
- libertas_quae_s 1mo agoThis! I also saw lot of potential work that could be done by linting tools. Remember to always prefer mechanical guards than agent instructions, as they cannot ignore them.
- bartread 1mo ago> Then this one really is a pattern that creates a lot of churn: > - Add a small, to the point, comment... As if you even need to tell Claude to add comments. Over the past few weeks I've noticed Claude over-commenting everything. Massive PRs where you realise that fully half or more of the lines that have changed are comments. It's no good at all: it just pollutes the context, causes token churn, ablates quality, and makes getting to a high quality outcome considerably slower and more expensive. I get that sometimes knowing why a thing is the way it is can be useful and valuable, but this is what commit comments are for in my mind. I've had to tell Claude to stop commenting code because the behaviour has become so problematic. > The what _is_ the code. Exactly. If I don't know what the code does because it's arcane and not commented I can simply ask the LLM to explain it to me. I don't need an essay in comment form.
- lucideer 1mo agoThis. We've been using agents heavily for all code for a long time now in my company - everyone has comprehensive & opinionated AGENTS.md customisations & they're widely shared & discussed. Almost everything in this post seems incredibly naive day-one LLM user mistakes - especially everything related to coding style at line level granularity. We've had non-LLM tooling for these kinds of standards for many years now & the great thing about agents is they're already versed in said tooling. If you haven't got a decent lint setup, ask your agent to set one up. It'll give you much better guarantees than this slop which is just going to drift from model to model & is completely unverifiable.
- andreareina 1mo ago# save the request headers for later because we don't yet know which one we'll need
- woud420 1mo agoA comment is just a summary of the code in an abstraction that's easier to follow. Let's say you have a simple function which would produce an almost as large comment, yes obviously useless. If the function is large enough, yeah summarizing it as a comment is a good idea. Now you might say, don't write huge functions. Sure I agree, but most codebase or teams are not super disciplined enough. So comments are a compromise.
- isqueiros 1mo agoComments lie. What's worse, AI trusts the comments and apparent logic (inferred from identifiers and whatnot) more than the actual logic. You can quickly get into a mess of stale comments. What's worse, the LLM can sometimes just spit out garbage that poisons the context of the next agent. I disallow comments from my LLM for that last reason.
- woud420 1mo agoCode can "lie" too. ```auto a = 65535 + 1``` will give you a different answer depending on the architecture. You can then decide.. oh don't use auto or don't use c++ or whatever and have standards... like the standard you set for yourself "disallow comments from my LLM".
- enraged_camel 1mo ago>> A comment is just a summary of the code in an abstraction that's easier to follow. I disagree. The code already tells you what it does. A summary has low value. Comments should be for explaining the why: the reason the function uses a particular algorithm even if it's a bit slower, or why the return format is an unconventional shape or contains redundant bits. This is so that someone coming in later (either a human or agent) doesn't get confused or think that the function needs refactoring. Summary comments have ended up as the bane of my existence everywhere I've worked, for one simple reason: they go stale and there's no way to prevent it from happening.
- woud420 1mo agoThat's your experience and it's valid. For me documentation AND comments have been useful on occasion. The core thing that I agree with is that comments (or docs) can get stale and not follow what is actually being executed. The way I work with it is by being structured, consistent and follow standards. Unfortunately for me, not all developers follow the same guidelines.
- EliasWatson 1mo agoAt my work we have basically banned "what" comments for blocks of code. JSDoc comments can still document what a function does at a high level but it should not go into implementation details unless they are important to anyone using the function. And any comments inside the function should always be for explaining why, not what. The "what" of a piece of code should be self explanatory by just reading the code. If it's not, then you likely should rewrite it to be more clear (sometimes hard-to-read code is necessary and then a "what" comment would be appropriate, but this is rare). "What" comments almost always end up falling out of date or even sometimes being slightly incorrect from day one. Incorrect comments lead to confusion and bugs. If a comment says some code does X but the code actually does Y, then you don't know whether the comment is just out of date or if Y is actually a bug. But if a comment explains the intention of the code and the code contradicts that intention, then you know it's likely a bug.