There are probably as many theories on proper commenting of your code as there are developers writing the code. What is worth noting? what is not? I think to much focus is wrapped up in rules that make writing good comments confusing to new and seasoned developers alike. I will go over a few simple rules I like to stand by.

1) Use XDoc comments wherever applicable. There are a number of tools out there that will make your life a lot easier when generating base documentation and HTML versions of your API documentation. They are quite useful.

2) Don’t comment just to comment. Quantity is not better than quality in most situations and this one is no exception. To many comments can be distracting and take you away from what is important; The code.

3) Answer the write question. To many times I read comments that always answer the question “What?” . If you can not easily read your code and determine what its doing you may want to consider addressing the problem a different way. There are a few exceptions to this rule with complex algorithms and methods, but you should use comments that answer this question minimally. The real question that should be answered is “Why?”. 6 months or 2 years down the road when you open up the code its probably going to be fairly obvious what the code is doing, what will not be so obvious is why you did something that particular way, some business based rule that was determined in a meeting that made sense at the time, is now just a big question mark. You will thank yourself when you don’t have to rewrite something just to figure out there was a reason you had done it that way.

4) Use examples. Even the best documentation and comments can leave confusion to people not as familiar with the code as you are. Be sure to include small snippets of code demonstrating how to use a class or method that you have created if there may be room for confusion.

5) Don’t be afraid of humor. Hunting down defects or just implementing a new feature can be long and tedious at times. At 3am when you or a fellow developer are knee deep in code you’ll appreciate the laugh it will remind you how much fun coding is.