Successful Strategies for Commenting Your Code

I ran into these very general commenting guidelines today:

Successful Strategies for Commenting Your Code

The author has done a survey of a number of authoritative references on good commenting conventions and makes notes of some commonalities among the references. He gives some examples of why these conventions are good. He also links directly to these references for more information. I think it's fairly well done.

I especially like one section:

On a more personal note, after I applied my findings to some of my recent projects, I noticed some significant improvements to my programming lifestyle:

• I was writing better code. By commenting everything, I was forced to think about why I was doing something rather than just making it work. I was programming smarter rather than harder. Because commenting my code forced me to verbalize my logic and make me think twice about a line of action when putting it into words, I usually found ways to optimize my code when it didn’t “sound right” to me. The comments lead to increased optimization and ultimately less work. Had I gone through after I finished a project to explain things, I’m positive I would have wasted a lot of time reprogramming and recommending bad logic. Time will tell if it decreased bugs as well.


• I was improving the future. You never know who’s going to be looking at your code or when you’ll need to refer back to it. Future Ryan, my co-workers, potential employers and even my mom are really going to appreciate my commenting investment, because it’s going to save them time. Time is money (especially in programming) and so shaving off time wasted on confusion and interpretation is definitely worth the effort.


• I was proud of my work. One of my biggest problems I have in my life is working on the same thing day in and day out. If I’m proud of what I doing, it basically removes that mental block. Because my projects were clean, flexible, efficient and sexy, I really enjoyed coming back to them and that, to me, is something priceless. Also, it makes it a lot easier to give a great first impression to job applicants, investors or even obsessive-compulsive blog readers when the code was created in a professional and consistent manner.