January 2012

Here are the most important reasons for including comments/documentation when writing code:

I absolutely believe in documenting code using both XML doc comments on methods as well as unlined comments when/where necessary. This facilitates docentation files being generated automatically and can be used to create .chm files. For all of us who are lazy or those that think it takes too much time, use GhostDoc. Thus, laziness is no excuse.
What if you have to maintain code that was written without comments? Do you want to waste your time digging thru code? What if it's more than just a method or class? What if its a library or framework? I personally have better things to do with my time.
What about someone new to your team? What if your the new guy? Is it easier to learn it with or without documentation/comments?
If you are writing a framework, library or API that will be used by other teams/API consumers, how are they supposed to know what it does without documentation? Do you expect them to dig thru your code to figure it out? What if they don't have access to the code? Would you want to have to do this?
What if you find some code without comments and the code looks wrong or inefficient? It's certainly possible that it was written that way for a reason. Only comments would help.
In addition to adding comments, code itself should be self documenting: use descriptive class, member, variable, parameter and method names.

When you write code, remember that you're not always going to be the one modifying, supporting it or consuming it...