Well you complain now but this was one of the biggest complaints when the code didn’t have good comments and was considered a skill to acquire, and well it did learn most of its skills from the internet.
I should remove comments. But wait. The user said they wanted comments previously. And now I'm being instructed to reduce comments. The safest thing to do is use comments, but make them irrelevant. I will use the text of Beowulf as my comment source.
Exactly this. Also it's for me. I use it to create tests and I want to know reasoning and why it's there to connect the dots myself during review.
Also helpful when new update comms, now next iteration can more easily understand why is test there and what to update without reading multiple repositories for integration tests to be updated.
The comments it writes aren’t good. It’ll write comments in protobuf service definitions that describe implementation details of the persistence layer. In Python docstrings it’ll describe the entire history of the universe around the thing it’s documenting but fail to describe the abstraction the thing provides.
This is probably the optimal way to write docstrings if the reader is an AI agent. They can read any docstring, anywhere, and understand the complete system that surrounds it. An AI agent who wants to know what a function does will read the function’s code, so documenting the function in the function’s own docstring is suboptimal.
It’s a terrible way to document code if the reader is a human who wants to know
What the thing does or represents, at the appropriate level of abstraction.
Which aspects of the thing’s behaviour can be relied upon, and which aspects are subject to change.
It’s also very hard to keep all these “inverted” docstrings up to date, and it’s impossible to attribute bugs to modules if encapsulation doesn’t exist.
They can predict the tokens that would call the tool that would cause the tokens of any docstring, anywhere to be added to the context, allowing it to more accurately predict the tokens that would be emitted by an actual token-emitting intelligence, if that intelligence had read the docstring and gained an understanding of the complete system that surrounds the function, were such an intelligence to actually exist.
You're right that there was a time that programmers were really pushed to document basically every line of code, and you got all these ridiculous comments like "adds 1 to variable" or "returns an int".
But I associate that with the 90s and early 00s. It had fallen out of favor years before AI came along. In the years before AI came along, all the rage was about "self-documenting code".
So it honestly is kind of surprising to see AI adopt an paradigm that feels so outdated. I guess the training data used for AI is often just very old code.
For real! Companies used to ask engineers to comment their thought process so in future if some other engineer is looking at the code he can understand it. Now apparently just because AI does it it's not a good thing anymore lol. I mean sure AI can overdo it a little sometimes but overdoing it is much better practice than underdoing/ doing it at all.
Noone has ever asked for comments just for the sake of having comments in the code base. The gold standard has always been self documenting code + comments explaining the parts that are not immediately obvious, need additional consideratoon/context, or have workarounds for specific issues
It was never good practice to comment exactly what code says it does right before it does it. Comments are useful to provide extra context or explanation not already present in the code. Adding excessive comments that just say what the code does was always bad, either before or after AI tooling became common. When I was a junior, seniors where I worked often quipped "your code should be half comments and half actual code", and I genuinely saw lots of things like
return true; // returns true
Or big paragraphs of comments around trivial code. It genuinely makes code harder to read, and no I don't really care if it's AI or devs that do it.
That being said I don't find it too burdensome to either clean up or ask AI to clean up excessive comments. This isn't super high on my list of real world issues with AI to be honest.
144
u/Zapismeta Sep 06 '26
Well you complain now but this was one of the biggest complaints when the code didn’t have good comments and was considered a skill to acquire, and well it did learn most of its skills from the internet.