Adding Class Descriptions To Code?

Question

I'm finishing up a project I've been working on for a while, and am just putting on the final touches.

One thing I would like to do is add class descriptions at the top of each class file (to help myself and other programmers figure out what's going on). My thought is to just use a bunch of '/''s to rope off a section for me to write some notes, but maybe there is a better way? Is there a built in way to do this in Visual Studio?

/////////////////////////////////////////////////////
//                                                 //
// KillZombies.cs                                  //
//                                                 //
// Description: This class contains blah blah blah //
//                                                 //  
/////////////////////////////////////////////////////

Answer 1

Yes, you should use the normal XML documentation:

/// <summary>
/// Describe your class quickly here.
/// </summary>
/// <remarks>
/// Add more details here.
/// </remarks>

That way it will show up in Intellisense, and if you build your documentation with Sandcastle/ndoc/Doxygen etc it will appear appropriately.

If you type "///" in the line above your class, you should see an appropriate template to get started. See the MSDN link above for more information.

Answer 2

Use XML documentation comments:

/// <summary>
///  This class performs an important function.
/// </summary>

When you type the three slashes Visual Studio will help you with the rest.

Don't use fancy ASCII formatting because when you refactor to change the class names you'll spend ages reformatting all your boxes to make them line up nicely again.

Answer 3

The XML documentation comments described in the answers above are the way to go for documentation of classes and methods.

If you require additional information in each file for non-documentation text, such as creation date, credits, copyright messages, and so on you could add it as a snippet or add it to the appropriate Visual Studio template. VS has special variables for templates such as $username$ and $time$ which can be used to automatically insert these values every time you add a new item based on your template.