Storing XML Comments in Separate Files

Problem
You’re concerned about XML comments causing clutter in your source files. You wonder if there are other options.

Solution
Use the include tag in XML comments to reference an external .xml file that contains the actual documentation.

Comments
Keeping XML comments in a separate file reduces clutter and allows two different people to work on the source code and documentation.

Examples
Here’s an example of how to use the include tag. First, prepare an XML file named doc.xml that includes the following text:

<?xml version="1.0" encoding="utf-8" ?>
<MyDoc>
    <Doc name="Account">
        <summary>
            An account type.
        </summary>
    </Doc>
</MyDoc>

Next, reference the documentation in the source like so:

/// <include file='doc.xml' path='MyDoc/Doc[@name="Account"]/*' />
public class Account
{
    ...
}

XML Comments in C#

Problem
You want to know when to use XML comments in C#.

Solution
Use XML comments to document all public types and their public members in an API (e.g. class libraries). Use standard class and method-level comments for types and methods that aren’t visible from outside the project.

Comments
XML comments have two great advantages. First, XML documentation can easily be generated by enabling an option on the Build screen of the Project Properties tab. Second is that NDoc can then be used to produce technical documentation for the API. The downsides of XML comments is they take up screen real estate and make comments less readable. However, you can collapse them and display them only when necessary. In addition, it may be advantageous to enable the XML Documentation File option only in release mode. Doing so will prevent slowing down the compilation process during debug and test phases.

Comment Position and Indentation

Problem
You want to know where to place comments and how they should be indented.

Solution
Comments should use the same indenting level as the code block it’s related to and immediately before it. There should be no blank lines in between.

Examples

// This is wrong. It's not indented and a blank line is used.
for ( int i = 0; i <= arr.Length; i++ )
{    
// Initialize the array element.

    arr[i] = i;
}

// This is correct.
for ( int i = 0; i <= arr.Length; i++ )
{
    // Initialize the array element.
    arr[i] = i;
}

Language Style for C# Comments

Problem
You’re interested in a recommended language style for code comments.

Solution
Favor an imperative style. An imperative style means that comments sound like commands you give to the code. For example: “Evaluate the button exists.”

Additional Comments
Alternatively, a descriptive style can be used. A descriptive style expresses what the code is doing. For example: “Evaluates the button exists.” One style sounds like a command, and the other describes what’s happening. Be consistent regardless of the style chosen. Otherwise, your comments may cause confusion.

Guidelines for Curly Braces in C#

Problem
You want to know where to place curly braces when defining a block of C# code.

Solution
Open and close curly braces on a line of their own.

Comments
Some folks like to use the C convention of placing open curly braces on the same line as the statement that defines the block. This style is fine as long as everyone working on the code consistently applies it. It’s a matter of preference that’s typically a choice between code readability and conciseness. I choose readability.

Example

// This style enhances readability.
void DoSomething(int x)
{
    if ( x == 0 )
    {
        ...
    }
    else
    {
        ...
    }
}

Wrapping Lines in C#

Problem
You want to know when to wrap long lines of C# code.

Solution
Use the following guidelines to help you decide where to insert a new line to split a long statement.

• Break a long line after a comma but before an operator. Beginning a new line with an operator makes it clear that it’s the result of statement splitting.
• Avoid wrapping a line in the middle of an expression, especially if in the middle of a parenthesized expression.
• Try to keep all items at a given nesting level on the same line.
• Don’t create excessively long lines if you later need to split them. Consider using temp variables to reduce expression complexity.
• Indent all wrapped lines by one tab.

Examples

// This is incorrect. A parenthesized expression is split, leaving an operator on the first line.
result = DoWork(first, second * (third +
    fourth));

// Both of these are correct, but the second one is better.
result = DoWork(first, second
    * (third + fourth));
result = DoWork(first,
    second * (third + fourth));