alt Hacker NewsSmart developers don’t write mazes.
> In code, comments are our signposts
No. Naming and good architecture are. Intuitive folder trees. Concise docs. Clear separation of concerns such that naming can suffice.
The more comments you need to ‘map’ your code, the worse of a job you’ve done.
Replies
> Smart developers don’t write mazes.
You don’t choose what your forebears have written, though.
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.
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 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.