Using Comments in Your Programming Source Code by Nicholas Brown

At some point every programmer has experienced it; returning to code written days or months before, you find yourself unable to remember why you wrote the code the way you did and what it was for. Nothing can be more frustrating or more time consuming than having to step back through code and figure out what was going on. There is, however, a way to reduce the risk of this happening again. Adding comments to your source code may seem like a waste of time now, but when you have to go back to a chunk of code months down the road, you will be very thankful you took the time to add a few explanatory comments.

If you have decided to start investing time placing comments in your code, allow me to give you a few “pointers” that will allow your comments to have the greatest impact. The first thing I do is place myself in the position of someone who has never seen that particular code before. I try to imagine I am this person, trying to figure out what the code before me is intended to do. I start out at the beginning of the code with an explanation of what the overall code is trying to accomplish. This will give the reader at least some idea as to what the code is intended to do.

Next, I give a brief description of what each variable’s role is in the code (i.e. counter, output, etc.). The person reading the code could eventually figure out what each variable is doing, but it is easier if you just spell it out for them.

Finally, I add the date. This is an extremely important step. It is extremely likely that sooner or later you will need to make revisions or corrections to your code. By including dates, you and others can see which pieces of code are the newest and which are the oldest. This can be extremely beneficial when debugging programs. I add a date, never erasing previous dates, each time I begin working in a piece of code. I also include a brief description of what was changed and why. This makes for a great reference log for later.

Many programmers find themselves reusing their code in different situations. Adding comments can help locate those needed pieces of code more quickly, saving valuable time. The important thing to remember with comments is that it not only benefits others, but will greatly benefit you in the future. Happy commenting!