Comments

Commenting your code is of great value if you (or anyone else) ever intends to look at your code in the future. Hopefully this is the case. But what do you write? What is important to include and what do you exclude? Lucky for you, I know the answer.

What to include

Put into your comments anything that will help you figure out why your wrote this code. Let me repeat myself. Tell the reader WHY this code exists.

Why is why so important? Most coders can read the code and determine what the code does at a basic level. I once worked on a piece of code that was very well written. Meaningful variable names, lot's of comments, nicely indented: generally well written. One problem: It was all in German, which unfortunately, I can't read. I was forced to read the code and understand its function, which I did. I successfully fixed the problem without the comments. Didn't I just prove comments aren't necessary? No, I proved they aren't required to understand function.

Why is useful at a much bigger level than the what of a piece of code. The why tells you how this fits into the bigger picture. It tells you its purpose.

You can put in a quick summary of what a method does and even explain the parameters to the method. I'm not opposed to any of that. If the code is particularly complex or confusing (perhaps a rewrite is in order) then the what can have some value. The purpose of a thing is far greater, since it explains the reason for its very existence. This does not change as the code is maintained. Code that is no longer necessary gets removed along with the comments.

What to exclude

Don't explain the obvious. Such comments are of zero value and tend to get out of sync as the code evolves.

Don't say in great detail what code is doing. When you do that you increase the maintenance load since not only the code needs to be updated, but so do the comments.

Examples of Bad Comments


Fatal error: Uncaught Error: Class 'format' not found in /home/abentley/www/pages/pgm101/comments.html:62 Stack trace: #0 /home/abentley/_framework/library/framework.php(126): include() #1 /home/abentley/_framework/library/framework.php(60): FRAMEWORK::include_file() #2 /home/abentley/_framework/library/framework.php(1466): FRAMEWORK::respond() #3 /home/abentley/public_html/index.php(4): include_once('/home/abentley/...') #4 {main} thrown in /home/abentley/www/pages/pgm101/comments.html on line 62