I made a discovery about commenting today. I've always known I am supposed to comment my code, I've heard about it a million times, but whenever I actually make a concerted effort to comment code while I'm writing it, when I come back on it later it is all about the wrong stuff and seems superfluous and is makes everything less clear by having random irrelevant blocks of text everywhere getting in the way. So I usually just end up deleting them all and grumpily repeating what my old mad guru would always declare (when I asked him about what the hell was going on with his cryptic pit of madness he wrote seven years ago): "The code is the documentation".
But then today I uncovered a long forgotten beloved project of mine, and I dove in to get it into some kind of working shape, now that I had the experience to actually do it right. Of course, there were no comments anywhere, and there were some mysterious things going on, so it took me a while to figure out what it was all about. But this time, every time I figured something out about the old piece of code I put a comment there, explaining what it was all about. By the time I was happily hacking away at it, I realized this was the best documented piece of code I had ever written. All the obvious things were left alone, and the bits that were unclear had commenting as necessary, rather than explaining every single line or function, and the whole thing had an explanation of the gist of how it is supposed to work together, and what it's for. Now if I ever come back to it years from now all those parts will be clear, and I will be able to get right into it. I realized I didn't need to write the comments the first time I write the code, because it is all clear in my head and I don't have perspective on what will be nonobvious when approaching it without context. So I figure it all out once, when I return to it the first time, and then document that process of discovery, so that when I return just the relevant bits will be there, and the rest I can work with unfettered code.
So anyway, YMMV, but I thought I would share this discovery for anyone who has had this same issue about commenting. And yeah, I know I still don't comment as much as I should. I blame my guru.