A dear friend and I were having a discussion just the other day about teaching. And we both agreed that, the thing about teaching that was so appealling was that, as a teacher, you often learn more than the students.
You can easily see how this is so by doing a little teaching yourself. And you can do that teaching by way of commenting your code.
First, let me give you a little background. I worked for a few years at a major oil company as their lead AutoCAD developer. I inherited a bunch of routines and code that had very little, if any, commenting at all. I had no idea what was being attempted most of the time and I spent the majority of my time isolating bits and pieces of code and figuring out the big picture one puzzle piece at a time. It was a wonderful learning experience but it was also a nightmare. And, to make matters worse, the guy who had the position before I did had a habit of naming his variables and his functions like this
(defun doit ( / a b c d)
There is no way I could have done my job without commenting his code. As I would figure out one piece of the puzzle, I would comment it, and move on to the next. That changed the way I looked at writing comments altogether.
The approach I take when I write comments in code (which, admittedly, isn't often enough) is this: Someone might be looking at that code a year from now trying to figure out what on earth I was trying to accomplish. And that person might not have the same skill level as I did (although that's not very likely) or that person may be new to LISP and my approach may confuse them... so I do my best to explain, in my comments, exactly what I was thinking and why. The approach that I took and why I took it. And, more often than not, my comments make up more than 50% of the text on the page.
That's good for a couple of reasons... first, and foremost, it gives a step-by-step road map of my thinking process when I wrote the code. Later, usually many months or years later, when I look at a bit of code I wrote, I can easily get right back on that train of thought. It also makes it fairly simple for someone else who might be reading it, to understand what is going on and why. If they don't fully grasp a concept, it's usually laid out pretty well in my comments. They can learn from my code and my mistakes. It can get them thinking on a similar track and, possibly, shed light on a problem that they may be having.
The biggest benefit to writing descriptive comments is that it helps you, the person writing them, to understand your code better. It usually ends up encouraging me to improve my already working code, because I'll realise that I could have done something better. It also points out mistakes in my code because, when I'm explaining it in the comments, it isn't until then that I'll realise that a particular piece of what I wrote wasn't necessary.
I've learned more from commenting my own code (and that of others) than you might believe. It's a valuable tool for you and everyone else.
When you take the time to comment your code in a thorough manner you are helping to teach others and you are helping to teach yourself.
I encourage you to make it a practice of yours, the benefits are well worth it.
