Wednesday, August 6, 2008

Auto-generate comments in C# .NET / Visual Studio

Apologies for not posting in a long time. I have a lot I would like to say, but as always, there's so little time to do it. Anyway, I knew I should post this before I forget about it.

So, I've been looking everywhere for how to do this, and I finally figured out how to do it. Hopefully some people searching for how to do this will find this , and it will be helpful.

If you've learned how to do .NET with an official curriculum, you may already know how to do this, but a lot of people, me included, have had to learn .NET sort of "by fire," without as much official instruction, since they were already familiar with similar languages, such as Java. When you learn by doing, sometimes you miss simple tips like this, and the .NET programmers probably already assumed everyone knows how to do this, because it's not even in the help files as far as I can tell.

I wanted to auto-generate comment blocks for my code like I have for quite some time in Eclipse. I believe the combination is alt-shift-J or something similar, and it's very useful to make sure that you properly document functions, classes, etc. However, I couldn't find any way to do that in .NET. Fortunately, I discovered that the correct way to do function comments in .NET is with three slashes - '///' - and that if you do that above a function, it will automatically generate a comment with the appropriate areas to fill in, etc.

I had assumed that the right way to comment was using "/**" blocks, and .NET happily created those blocks, complete with automatic *s at the beginning of every line. However, it never gave me the place to put things like parameters and output, much to my dismay. However, if you use '///' instead, it generates the kind of headers I'd expect. They're formatted in XML syntax, which is fitting with .NET's methodology. Anyway, I'm now living in a happy world of comment blocks with auto-generated formatting and names, which is a great change. I just wish it had been a bit easier to find this information-I already documented one of my projects by hand, and I'm sure I forgot some parameters or something along the way.