Documenting your C# Source Code

Many programming languages have a standard for inline code comments, and C# has supported such a standard since its initial release. The C# code commenting standard is based on a syntax known as XML Comments. These are simply code comments that adhere to an XML structure.

XML Comments

All XML comments are added to C# source code by prefixing the comment lines with three forward slashes, ///. To make it easier to add properly formatted comments to source code, Visual Studio.NET will automatically insert a documentation template whenever three forward slashes are typed within a C# source code file. Although XML comments may be placed in any part of the application source code, it is most common practice to ensure that XML comments are inserted immediately before the definition of classes, methods and properties. An example of a C# method documented with XML comments is shown below:

/// <summary>  
///<para>Non-HTML files like Adobe Acrobat PDF files and Word  
///documents are stored with their original URLs partially  
///encoded in their filenames. This function will return the  
///original URL of the file.</para>  
///<para>The encoding done by the Index Server Companion removes  
///characters that cannot be present in Windows filenames  
///(these are: \/:*?"<>|). The decoding performed is:</para>  
/// <list type="table">  
/// <listheader><term>Find</term><description>Replace</description></listheader>  
/// <item><term>^f</term><description>\</description></item>  
/// <item><term>^b</term><description>/</description></item>  
/// <item><term>^c</term><description>:</description></item>  
/// <item><term>^s</term><description>*</description></item>  
/// <item><term>^q</term><description>?</description></item>  
/// <item><term>^d</term><description>\</description></item>  
/// <item><term>^l</term><description><</description></item>  
/// <item><term>^g</term><description>></description></item>  
/// <item><term>^p</term><description>|</description></item>  
/// </list>  
/// </summary>  
/// <param name="FileName">The document's original filename.</param>  
/// <returns>Decoded filename</returns>  
/// <exception cref="System.Exception">Throws an exception when something goes wrong.</exception>  
private string CreateURLFromFileName(string FileName)  
{

    try  
    {
        //Remove o_ prefix from URL  
        FileName = FileName.Substring(2, FileName.Length - 2);

        //Remove other encoded characters  
        FileName = FileName.Replace("^f", "\\");
        FileName = FileName.Replace("^b", "/");
        FileName = FileName.Replace("^c", ":");
        FileName = FileName.Replace("^s", "*");
        FileName = FileName.Replace("^q", "?");
        FileName = FileName.Replace("^d", "\"");
        FileName = FileName.Replace("^l", "<");
        FileName = FileName.Replace("^g", ">");
        FileName = FileName.Replace("^p", "|");
        FileName = FileName.Replace("^f", "\\");
        FileName = FileName.Replace("^f", "\\");
        FileName = FileName.Replace("^f", "\\");
        FileName = FileName.Replace("^f", "\\");
    }  
    catch  
    {

    }

    return FileName;

}

XML comments have a defined set of XML tags for documenting a method's purporse, arguments and return values. These standard XML comment tags are designed to allow most source code to be comprehensively documented, although it is also possible to define your own custom sets of tags.

Further Reading

• The .NET Documentation Tool for C# (VB.NET also supported).