A Harsh Lesson On Commenting

I ran into one of my psuedo-bosses, Bill Wagner, at P.F.Changs (I like my Change Sauce spicey unlike my partner-in-crime, John Hopkins) where he was having lunch with Tim Landgrave. After a friendly introduction, we somehow got on the topic of commenting. That's when Bill made the comment, "Darrell, comments start with 2 '/'"! I was so insulted! I said I commented my code, but in my head I was thinking "I kind of comment my code". Well, it turns out the next project Bill had me do was to do a code review of all of the code that has been written for this project over the past 2+ years. This is when I learned that I had no idea what commenting meant. Allow me to share with you what I've learned...

• I can confuse myself with my own code
• Even simple functions can be confusing without a stated purpose
• Speaking of purpose, every class has one. Put it in an xml comment.
• Ditto for functions
• It's not good code, unless it's commented code (THIS IS THE MOST IMPORTANT LESSON OF ALL).

Now that I am done confessing my sins, let's talk about the future, shall we? I'm going to be starting a new series of blog posts on WCF (Windows Communication Foundation). Unlike my WSE series, I'm not going to have pre-stated goal. I simply want to share what I've learned. As part of this series, I will be including short webcasts to highlight the important stuff. I hope to start sometime in the next week, but I have some items to get done first.

And don't forget CodeMash