@jk Any engineer who tells you that well-written code is self-documenting has failed to understand the question: code can only tell you _what_ it is doing. It cannot tell you _why_. It cannot answer the fundamental question "what made this design the right choice, as opposed to any other implementation, based on the constraints that existed when we wrote it?" As such, even the best-written code cannot truly "self-document."
@literorrery I wonder how much of this is a result of folks teaching commenting badly?
@indi I suspect so. Most people teach commenting as "what is it doing." We can see what it's doing. What we can't see is "why is it doing this and what do you need to watch out for if you try to change this." Changing people's attitudes on what commenting is for would go a long way to helping solve that.
@literorrery Yeah exactly; I've HEARD the aphorism "Comment the why, not the what" but I'm not sure I ever heard it when I was learning programming in the first place.
@indi I know I never learned it in college, which is when I should've gotten it. I picked it up from every terrible source file I ever read that had "this is a hack and needs to be refactored but will get us up and running" somewhere in it that told me "oh, this _isn't_ the right way, just the right-now way. This isn't sacred. I can fix it and make things better!"
Between that and "how to review code," I swear, there's a whole "how to code" that college just does not teach and should.