Comment your code
Make extensive comments in your code. Explain what your code is doing, even if it is obvious.
Date : 2006-06-14
It's easy to think that a specific line of code, or small function is going to be clear to you no matter how long it is before you see it again. It is still important to add comments.
Adding comments gives the next programmer that sees your code a chance to understand what you are doing. It also gives you a chance to read through your logic at a later time and make sense of it.
Storing your logic or psuedocode in your comments is a good way to keep yourself organized while programming.
A comment block before functions, subroutines, and classes to explain their purpose and parameters is a must. Don't question it, just do it. The same thing can be said about included libraries of code. Create a block of comments at the top that describes each function, subroutine, and class. Yes, this will create multiple instances of your comments but it is necessary when dealing with large amounts of code to keep things straight.
Maintain your comments. If you remove or add a function to your includable library make the necessary adjustments to your comments.
If you comment out a section of code for any purpose, write your name, the date and time and why you commented the code out. If there was a specific purpose or an ongoing reason. If the code is going to be removed for good then remove it don't just comment it out.
Sticking to a rigid set of code commenting rules will make you a much more efficient programmer. You may feel like it is a waste of time that could be spent in hard core coding, but if that time is wasted later in debugging or when you go to add a feature then what's the point.
No comments yet