I'm with you in spirit but I'm not shocked given how many people say that they don't need to write docs because their code is so well written that it is self documented. Which tells me your code is any combination of 1) spaghetti 2) highly unoptimized 3) a holy piece of text. What's the saying? 30 years of improvements in programming has completely undone 30 years of improvements in hardware? Moving fast and breaking things is great to get going, but eventually someone has to come around and clean up all the mess.
I never heard people say their code was well written (I wouldn't personally), but many of us have stopped reading docs and comments outside of specifically added ones in surprising locations and vendor provided doc.
Many orgs have mandatory docs and comments, yet the devs find nothing specific to write about (they already wrote design documents), and deeply down in their heart don't want to maintain it either. So you get bland and sometimes inane docs and comments, with a bunch of it going stale for a combination of reasons. To the point where you feel you lost your time reading that prose 9 times out of 10, when it wasn't straight misleading/factually wrong.
It takes real dedication, discipline and talent to have good documentation, and I wouldn't expect any random dev org to be able to pull it off.
> I never heard people say their code was well written
It's shockingly common...[0]
TBH there's very few people I've worked with that document, comment, or any form of help. You can see in that thread that much of my frustration in work (including big tech) is that people hand be aliases and call them scripts or hand be hard coded spaghetti and expect me to figure it out without handing over any of the files. But I'm also a researcher, but I have worked on some projects in big tech and this happens more.
> It takes real dedication, discipline and talent to have good documentation, and I wouldn't expect any random dev org to be able to pull it off.
I don't disagree, but I think writing docs makes a better programmer. You have to think more about your code and methods. It's like the Feynman technique of learning: teach others. I generally write docs for myself because I need to remember. Because writing comments helps me not rush and think a bit more about what I'm doing and where I'm going or could go. As a researcher I'm changing what I'm doing all the time so the latter is quite useful, thinking what I'm going to come back and hack on and making it easier or providing myself hints to come back and rethink. You're right, it takes more time, but often it is faster too. I definitely think it has made me a substantially better programmer and why shouldn't it? A professional athlete reviews their performance, analyzes, criticizes, and rethinks their plan of attack. Are we not doing the same to better ourselves? I hope the pay we get is enough to not just check out and coast but I don't want to be average. I want to be better than I was a month ago.
