I once had an English teacher who, whenever she was asked how long a research paper should be, would reply, “Like a nice woman’s skirt – long enough to cover the subject but short enough to keep it interesting.” In much the same way, a good developer should comment their code enough to keep the code organized, explain areas that contain logic which may not be immediately obvious, and generally make the code more readable to another developer, or even to a future version of yourself who doesn’t remember why you did something the way you did it two years ago. Any developer with more than a few months under their belt can tell you that they have revisited an old bit of code they wrote and thought to themselves, “What was I thinking?!” By following a few simple guidelines, you can integrate comments into your code without having to spend a lot of time doing it. These tips apply to any code, be it C++, Java, ColdFusion, PHP, .NET, or even database scripts from SQL Server, MySQL, or Oracle.
Make Use of Comment Blocks
The first and probably easiest way to start properly commenting your code is to begin each page with a short comment block consisting of the date, your name, and a brief summary of what this page or bit of code is intended to do. We may think that the file name should make it obvious what a block of code does, but as any developer sifting through hundreds of similarly named files can tell you, it really helps to have a short, specific description at the top of any code block. In addition, this gives other developers a place to quickly add another comment if the code has some significant change made to it at a later date. The comments at that time might include the new date, the name of the developer making the change, and a brief but specific description of the change being made and possibly even the reason for it.
Use Psuedo Codes
Another easy way to comment your code is to begin with a pseudo code as comments, filling in the areas with real code afterwards. You may start with a comment like, “Initialize global variables.” As you proceed, you may have a section called, “Query the database for customer orders,” followed by “Loop through the customer orders and gather order details,” then “Calculate totals” and finally “Display order data and totals.” As you come back to actually write the code for each section, your comments may already be enough to suffice; you do not need to include a comment for each variable you initialize if you include all of your global variables underneath your original comment. This not only saves you from doing additional work, it makes more sense and breaks the code into organized, readable blocks where another developer knows to look if they are trying to find a given variable.
Explain What Isn’t Obvious to Others
For the other sections, there may or may not be a need for further comments as you write the actual code. For instance, if all you are doing in the loop is what you have already described, then your commenting job is done. However, if you do something that may not be immediately obvious to another developer, like “ignore customer order lines containing Product ID “BR-JAN” (a free brochure being included with every order in January)”, you may want to jot down a brief note as to why you have a conditional statement in the loop that skips any order line containing that product ID. Any good developer should avoid hard coding things like IDs inside of code, but any experienced developer knows this is a rule that will be broken at some point, and a quick note explaining why it’s being done will go a long way in making the code readable later. If this page gets refactored later, a comment like that may also prompt you to ask some important questions about the model or the query that retrieved the data in the first place. Could the query have excluded these items before your loop? Should there be a product type for brochures that would automatically exclude them from reports with order details?
Avoid Using Numbers
One last tip about commenting is to keep in mind that code tends to grow and morph during its lifetime, so try to avoid using numbers or words (first, second, etc.). These types of ordered lists will inevitably end up being wrong at some point, and depending on the length of the list, it can be a real nightmare to go back and try to renumber all of your comments. Many times you will find that even before you are finished with a single page of code, you have moved entire sections around, so keep your comments general enough that you can move them with the code and do not have to rewrite them.
As you can see from the examples above, commenting your code does not have to add significant time to your development efforts, and the benefits that you or your colleagues will reap from having well organized, easily readable, and easily maintained code will more than make up for a couple of minutes taken to add good comments up front.