I completely agree with you. When I write code, the actual code only captures a small fragment of the total mental model that is my solution to the problem at h

I completely agree with you. When I write code, the actual code only captures a small fragment of the total mental model that is my solution to the problem at hand. There is so much information about the problem that is not captured purely in code that a maintainer would need to know to make well-informed decisions about the system going forward. I have been fortunate to be in the position of handing off my work to a colleague. Knowing I had left a well-documented system behind was a great satisfaction. The only time commenting becomes difficult for me is if I am in a team where I know I will be the only one maintaining good comments. It takes no effort to update comments as you code but if I am the only one doing it then it becomes a problem.