Comments

Okay, I realize this is a techie blog, so there should be some technical meaning to this post. Accordingly, I'll post my thoughts on commenting the code you write.



The real reason for this post, however, is mostly to point out that I've turned the comment feature back on for this blog. As I pointed out in a post to my personal blog, Blog*Spot had some trouble with spam. It seems to be all better now, and I've had the commented turned on in my other blogs with no trouble for more than a week now.



Back to the relevant topic: comments. Developers have been arguing for years over what should be commented, and what shouldn't be. The rule of thumb I use is that the code itself should tell the what, not the comments. If you can't look at the code and easily determine what it's doing, you need to refactor it.



So then, what are comments for? The comments should tell the why. That's my rule of thumb: the code tells the what, the comments tell the why.



Maybe you wrote some code that deletes a file. The what will be fairly obvious. But why are you deleting this particular file? Here's an example:



In C#, you can also include XML comments. Visual Studio will automatically create an XML comment stub for you if you type 3 comment slashes (///) immediately preceeding a method, or other commentable element. (Note that there are several 3rd party add-ins that allow you to auto-create XML comments in Visual Basic).



When you're finished, it looks something like this:



XML comments are exceptionally useful, and I recommend them highly. First, they remove the need for those painful block comment headers that some companies require. You know the ones - they have such important information as the programmer's name and the date the method was written (because nothing will help me debug like knowing that something was written 3 months ago).



If you specify a file path in your project properties, Visual Studio will create an XML file of all the comments for you during compilation. To set this up, set the XML Documentation File in build section under Configuration Properties from the project properties window as in the following example:




If you create an XML, then a snazzy tool like NDoc will pick up the file, use a little reflection, and create an instanct CHM help file to document your code. Viola! Instant documentation. Few things make a developer happier than not having to waste time writing doc.



Even if you don't plan on creating documentation, there's another reason to use XML commenting. Intellisense looks for it when showing you a method signature. Look what happens when I use the UserHasPermission method from the example above:



This could be extremely helpful if you need to reuse someone else's code, or if somebody needs to use yours.



So the lesson in all this is:

1. Code tells the what, comments tell the why
2. Use the XML comments feature of visual studio
3. I turned the comments back on for this blog, so you can leave some

Happy coding!