Writing great comments is the kind of thing you really have to learn the hard way. When I first started coding, I used to comment my code in what I call the "micro-comment" format (comments that describe a single line of code). In my case, I had a project that I had to abandon for a period of few months. When I had to go back into that project to fix up some things, I couldn't anything, despite my micro-comments. I actually had to completely abandon a 20,000 line code base of a personal project because I couldn't read the code. That vivid experience of personally feeling the pain of my bad commenting is what taught me how to comment properly. I kept asking myself "Why the fuck did I do that? What is this code doing? Jeez, these comments are not helping me at all".

Now when I write things, I know to comment in what I call the "macro-comment". That is to say instead of writing a comment to describe a single line of code, you write comments to describe a block of code. Since that one project's fail, I haven't had that problem again.

Another point I want to make is that I really feel like my commenting skills are extremely valuable to me as a developer. I I had to have my brain erased, but I could choose one skill to remain, I'd choose keeping my code commenting skills. Its also the one skills that I care about the most in my co-workers. I don't care if you're really good at code golf. I don't care if you know haskell. Can you comment code properly? Whenever I interview for a job, I'm never able to demonstrate this skill. The Fizzbuzz problem doesn't allow me to show off my commenting skills. Writing a binary tree parser doesn't let me show off my documentation skills. I think it's the most important skill I have, but I never get the chance to show it off when interviewing.