Always Use Comments

When writing code, strive to make it self documenting. You can do this by following the guidelines that I gave in related posts. However, self documenting code is elusive quarry. Like the pot of gold at the end of the rainbow, you can never quite reach it, even though it seems to close. The remedy for this is good comment. Most important thing for you to know is that what separates a good comment from a bad comment?

Generally speaking, a good comment operates at the level of intent. A good comment answers the questions, “What was the programmer trying to do with this code? Where does this code fit in with the overall scheme of the script? Why does this code exist?” The answer to these questions, fill in the blanks that can never be filled by even the best self-documenting code. Good comments are also generally “paragraph-level” comments. Your code should be clear enough that you do not need a comment for every line, but a comment that quickly and clearly describes the purpose for a block of code allows a reader to scan through the comments rather then reading every line of code. The idea is to keep the person who might be reading your code from having to pore over every line to try and figure out why the code exists.

Bad comments are generally redundant comments, meaning they repeat what the code itself already tells you. Try to make your code as clear as possible so that you don’t need to repeat yourself with comments. Redundant comments tend to add clutter and do more harm then good. Reading the code tells you the ‘how’; reading the comments should tell you the ‘why’.

Finally, it’s a good idea to get into the habit of adding “tombstone” or “flower box” comments at the top of each file, module, class, and the procedure. These comments typically describe the purpose of the code, the date it was created, the original author, and a log of modification.