"don't write comments, just write clear code" yeah and also write comments
@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."
@hellojed @jk Oh, I'm totally down for "clean code," and I totally agree that maintainable code far outstrips the alternative. I'm suggesting that "readable code without comments" is still harder to maintain than "well-commented messy code" because well-commented code will tell me what it's trying to do, which lets me validate developer assumptions against software behavior. Code can't do that by itself. :)
@hellojed @jk @literorrery Comments are good, but they get outdated after a while. The commit history is maybe a better place for the justifications to belong.
@brennen @literorrery @jk that'd be really nice, yeah
@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.
@literorrery @jk Anyone who tells you that well-written code is self-documenting is lying to you.
The real test of well-documented code is when you can pick it up in 6 months and say, "Oh, yeah, *that's* why I did this!"
@literorrery @jk I am totally in the 'write self documenting code' camp.
I don't think there's a perfect solution but I do end up adhering to a lot of "clean code" practices that I adhear to make code a lot more maintainable.
I think a lot of people are obsessed with writing "perfect" code when really we're just trying to smash rocks together to display text on a screen so we can make food money