Great post, so true. One point I'd add, though: when you're writing code, make it readable by commenting well! Sure it's obvious to you why you used a ternary operator expression that uses a postfix-decrement operator and raises an exception, but that's not clear to me. Until you tell me that you're testing to see if an object reference count is zero, decrementing it if not, and raising an error if so.
Good comments are tedious work and seem pointless at the time, but just wait until you're reading your own code two weeks later, or even worse, someone else's. The time you spent explaining yourself frequently makes up for the time you'll waste later reimplementing what you did the last time around.
> Until you tell me that you're testing to see if an object reference count is zero, decrementing it if not, and raising an error if so.
But that won't tell me why your code is doing what it's doing
> Good comments are tedious work and seem pointless at the time,
Good comments should make you think about your code, not be some pain point you are compelled to endure.
If you think it's tedious and pointless, there is a good chance the reader (quite possibly yourself not to far in the future) will consider the comment tedious and pointless as well.
> But that won't tell me why your code is doing what it's doing
Indeed, that's what the rest of the comment is for.
> Good comments should make you think about your code, not be some pain point you are compelled to endure.
Fair point. Yet the fact is that many people enjoy neither commenting nor thinking about their own code, and that's not going to change. The question is how to convince people to write good documentation in the face of intrinsic motivations not to do so, and I think the best persuasion is a reminder of how they will use that documentation later.
Good comments are tedious work and seem pointless at the time, but just wait until you're reading your own code two weeks later, or even worse, someone else's. The time you spent explaining yourself frequently makes up for the time you'll waste later reimplementing what you did the last time around.