Comments & XML Documentation — C# Reference, Syntax & Examples

Read the syntax

// comments run to the end of a line; /* ... */ comments span a region. The compiler ignores them, so they explain code without changing its result.

/// introduces XML documentation for a declaration. Tags such as summary, param and returns describe an API for editor tooltips or generated documentation; they do not call the method.

Syntax

// single-line\n/* multi-line */\n/// <summary>XML doc</summary>

Examples

Single-Line and Multi-Line Comments

The two basic comment styles.

// Calculate the area of a rectangle
int width = 5;
int height = 3;

/*
 * This is a multi-line comment.
 * It can span several lines for longer explanations.
 */
int area = width * height;
Console.WriteLine(area);

The two basic comment styles.
// comments run to the end of a line; /* ... */ comments span a region. The compiler ignores them, so they explain code without changing its result.
width * height calculates 15, which WriteLine prints. The comments describe why the calculation exists and demonstrate both comment forms without affecting the multiplication.

XML Documentation Comments

Documenting a method so IDEs can show rich tooltips via IntelliSense.

Console.WriteLine(MathHelpers.Average(4, 6));

public static class MathHelpers
{
    /// <summary>
    /// Calculates the average of two numbers.
    /// </summary>
    /// <param name="a">The first number.</param>
    /// <param name="b">The second number.</param>
    /// <returns>The average of a and b.</returns>
    public static double Average(double a, double b)
    {
        return (a + b) / 2;
    }
}

Documenting a method so IDEs can show rich tooltips via IntelliSense.
// comments run to the end of a line; /* ... */ comments span a region. The compiler ignores them, so they explain code without changing its result.
The XML tags describe Average and its parameters, while return (a + b) / 2 supplies the method’s result. The call with 4 and 6 prints 5.

Commenting Out Code

Temporarily disabling a line while debugging.

int total = 0;
for (int i = 1; i <= 10; i++)
{
    total += i;
    // Console.WriteLine($"Running total: {total}");  // disabled for now
}
Console.WriteLine(total);

Temporarily disabling a line while debugging.
// comments run to the end of a line; /* ... */ comments span a region. The compiler ignores them, so they explain code without changing its result.
The for loop adds 1 through 10 to total, so the final line prints 55. The commented WriteLine never executes; remove // to observe each intermediate sum.

Best practices

Add /// XML doc comments to public classes and methods, especially in libraries - IntelliSense and generated documentation both rely on them
Explain *why* code does something in comments, not *what* it does - the code itself should already communicate the "what"
Keep comments up to date - a comment that contradicts the code it describes causes more confusion than no comment at all
Use <param> and <returns> tags consistently in XML doc comments so tooltips show complete, accurate information

Runtime & versions

.NET runtime. Feature availability depends on the language and runtime version used by your project; consult the official reference below.

C# language reference

Specifications & further reading

C# language reference