Too much, or not enough?

Commenting code is a difficult thing for a lot of people. It is hard to maintain the delicate balance between too much commenting and not enough commenting. Well, here are some things to  consider about commenting.

Too much commenting is:

• better than no commenting as a person reading your source code can still understand what is happening.
• not a replacement for bad code.
• can make your code unreadable as a reader has to scroll through large amounts of comments to find an interesting bit of code.

Not enough commenting is:

• not being very nice to anybody reading your code.
• going to cause you problems in the future when you forget the purpose of complex bits of code.
• bad as few people might be able to understand the logic behind the way something is coded.

Commenting in general is good because:

• you will understand what is going in your code when you leave it alone for a year or two.
• it makes you think about the logic behind your code and ways to improve it.
• it is a good place to work on your documentation if you use phpDocumentor or Javadoc.

When commenting goes bad

Some cases, commenting affects the performance of an application. Normally, comments are ignored by the parser, compiler, or interpreter. However, if you are parsing or compiling code that is made up of entirely comments, clearly that is a waste of resources.

An example of this occurring in PHP would be in WordPress. Yes, WordPress actually uses comments that waste resources. A standard WordPress installation has many directories. Most directories have an "index.php" file to prevent users from seeing the contents of that directory as many servers will display the contents of a directory if an "index" file is not present. You can prevent directory listing, but clearly WordPress shouldn’t be messing around with the server’s configuration. That’s why the "index.php" files exist.

To get to the point, these "index.php" files sometimes are composed entirely of useless phrases that are commented out like "Silence is golden". Getting the PHP interpreter involved for just a small phrase that’s commented out doesn’t seem like a very efficient idea at all. The best idea would be to have an "index.html" file and have the phrase in HTML comments or just displayed on the screen.

Conclusion

Too much commenting is better than no commenting, never waste resources just for comments, and PLEASE comment your code to make jobs of the rest of us easier.