Kyle Schouviller

I admit, I used to hate commenting code. It took so much time, and I was constantly changing the code anyway. Every time I’d code something, I said “I’ll comment it once it’s done.” Every time I finished something, I’d immediately start working on the next piece. After all, it took a lot of time to comment things, the comments weren’t even that easy to read, and I had better things to be doing.

Then, about a year and a half ago, I started using C# and discovered the joy of commenting in Visual Studio 2005 (and the express editions). It’s still not a blast to comment things, but it is much easier, and your comments can actually be useful (besides the obvious usefulness of being able to figure out what you meant to do last Wednesday at 4:00 AM!). This ease and usefulness are all wrapped up in the triple-slash, ///.

Go ahead, open Visual Studio and create a new enumeration. Then, click on the blank line above that enumeration, and type three forward slashes, ///. See what Visual Studio did for you? The Visual Studio IDE will create a comment block that outlines the information for whatever is on the line following the triple slash. This can be as simple as a summary block or as complex as detailing all the fields of a method.

It’s easy to add more information, too. Just add another triple-slash line below the current block and type a less-than symbol (<), and check out the list of things you can add. You can add samples, remarks, seealsos, and much more!

So it’s really easy to comment chunks of code now. So what? Having three lines of comments for a simple enumeration doesn’t seem like an improvement. What’s with all the XML stuff anyways?

Well, triple-slash comments are XML comments, and they are used to generate documentation. This includes both intellisense documentation and XML output documentation (more on this in a bit). You know how the intellisense information will usually include a little sentence about what the class or method does? For example, it tells us that a String “represents text as a series of Unicode characters.” Well, you can do that with your own classes, methods, enumerations, etc. Look at what happens when I try to use the enumeration I made earlier:

It also helps me make better use of my methods. Not only does intellisense tell me what a method does, it’ll also tell me what sorts of things I should use for that method’s parameters:

See how useful that can be? You can even export all of your documentation to an XML file, which you can then include with your code, or even post on a website. In fact, with a nice XSLT file to accompany your XML, you could have some pretty nice online documentation for your code.

To generate documentation, go to the Build tab of the project properties dialog (right click on the project in the solution explorer and select “Properties”), then check the “XML documentation file” checkbox in the Output section. Now, whenever your project builds, it will generate a nice XML file with all of your documentation. If you’re making a library for others to use - especially if you’re just releasing it as a pre-compiled dll - this is extremely useful!

Finally, you may notice that when you generate XML documentation you end up with a ton of warnings in the error list when you build your project. If not, congratulations, you’re a great commenter! Visual Studio will let you know when you haven’t commented something (in most cases) by giving you a warning during building. This won’t stop you from running your project, but it will help you find places you need to comment so you can output effective documentation.

So please, use the triple-slash to comment your code - and comment as you go. It makes life easier on everyone who touches or uses your code in the future - whether it’s you, your team, your coworkers or someone who’s using your components.

This entry was posted on Sunday, March 18th, 2007 at 8:29 pm and is filed under CSharp, Code Bits, XNA. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.