> It's infuriating. Nearly all of the agentic coding best practices are things that we should have just been doing all along

There's a good reason why we didn't though: because we didn't see any obvious value in it. So it felt like a waste of time. Now it feels like time well spent.

Huh. It's displayed taking up three cells in my terminal, but laid out as if its width were one cell. Irritating. I wonder if there are any other grapheme clusters that don't properly fit in two cells?

Idk if u are serious.

Yes, lets blow another 5-10k a project/month on tokens to keep the comments up to date. The fact ai still cannot consistently refactor without leaving dead code around even after a self review does not give me confidence in comments…

Comments in code are often a code smell. This is an industry standard for a reason and isnt because of staleness. If u are writing a comment, it means the code is bad or there is irreducible complexity. It is about good design. Comments everywhere are almost always a flag.

Note, language conventions are not the same.

Actually good naming does plenty to explain the why. And because it’s part of the code it might actually be updated when it stops being true.

Comments are great until they diverge from the code. The "no comments, just self-explanatory code" reaction comes from the trauma of having to read hundreds of lines of comments only to discover they have nothing to do with how the code actually works, because over time the code has received updates but the comments haven't. In that case it's better to just have no comments or documentation of any kind--less cognitive overhead. This is a symptom of broken culture, but the breakage is the same kind that has managers salivating over LLM vibeslop. So I totally get where your colleagues might be coming from. Working within the confines of how things actually are it could be totally reasonable.

> the code should explain itself.

This is a good goal. You should strive to make the code explain itself. To write code that does not need comments.

You will fail to reach that goal most of the time.

And when you fail to reach that goal, write the dang comments explaining why the code is the way that it is.

People moving docs out of code are absolutely foolish because no one is going to remember to update it consistently but the agent always updates comments in the line of sight consistently.

Agent is not going to know to look for a file to update unless instructed. Now your file is out of sync. Code comments keeping everything line of sight makes it easy and foolproof.

That’s what a source map is. It’s included in debug builds so that browser debuggers (and others) can step through the original code, comments and all, instead of the compiled javascript (which back in the day could become an undecipherable mess of callbacks if you were transpiling async/await to the legacy Promise API).

Unfortunately in many bundlers making a mistake like this is as easy as an agent deleting “process.env[‘ENV’] === ‘debug’” which they’ll gladly do if you point them at a production or staging environment and ask them to debug the stripped/compiled/minified code.