I absolutely agree that those things should take priority, but I think those things can only go so far and there's a threshold of complexity beyond which there will always be some benefit to comments. You can absolutely reduce the need for 'signposts' if you avoid creating a maze.

As others have said, you didn't always build the maze. Or you built a lovely intuitive path and then were hit with an unexpected new requirement that forced you to add twisty little passages. Or, like me, you're not a perfect being and had to compromise based on some complication you didn't expect.

> Smart developers don’t write mazes.

You don’t choose what your forebears have written, though.

Everyone disagrees about Good Architecture and it changes with new technologies btw

Years ago I worked on a project that had a n tier architecture and facade pattern for the frontend

It was good architecture for the lead developer who set it up but bad for the new team who need to update the tech

So comments and docs are both valuable

Nowadays with AI the calculus has changed once more

I'm afraid this all gets thrown out the window nowadays.

Unless I tell them not to, LLMs lean on slapping verbose comments of the worst kind - describing the code instead of the reasons for putting it there.

I ask them to write comments in ASD-STE100 Simplified Technical English, but all I really get from that is tersness.

Also the other day I stumbled upon a huge pile of documentation and I'm still trying to figure out if it's human or machine written. I stopped reading it half way through as I figured that perhaps it wasn't written for humans to read.