C# Comments : A Tutorial

In C#, comments are used to add explanatory notes to code.

They are ignored by the compiler and serve to:

• Improve code readability.
• Explain complex logic.
• Temporarily disable parts of the code.

C# provides three types of comments:

1. Single-line comments (//)
2. Multi-line comments (/* … */)
3. XML documentation comments (///)

1. Single-Line Comments (//)

Single-line comments start with // and continue until the end of the line.

Example:

using System;

class Program {
    static void Main() {
        // This is a single-line comment
        Console.WriteLine("Hello, World!"); // This prints text
    }
}

Use Cases:

• Explaining a line of code.
• Temporarily disabling a line of code.

Example: Disabling a Line of Code

int x = 10;
// Console.WriteLine(x); // This line is commented out and will not run

2. Multi-Line Comments (/* … */)

Multi-line comments are enclosed within /* and */. They are useful for commenting out multiple lines.

Example:

/*
This is a multi-line comment.
It spans multiple lines.
*/
Console.WriteLine("Hello, World!");

Use Cases:

• Commenting out large blocks of code.
• Adding detailed explanations.

Example: Temporarily Disabling Code

/*
int x = 10;
int y = 20;
Console.WriteLine(x + y);
*/
Console.WriteLine("Code is temporarily disabled.");

3. XML Documentation Comments (///)

XML comments are used to document classes, methods, and properties. They start with /// and can generate API documentation.

Example:

/// <summary>
/// This class represents a simple calculator.
/// </summary>
class Calculator {
    /// <summary>
    /// Adds two numbers.
    /// </summary>
    /// <param name="a">First number</param>
    /// <param name="b">Second number</param>
    /// <returns>The sum of a and b</returns>
    public int Add(int a, int b) {
        return a + b;
    }
}

Use Cases:

• Documenting classes, methods, and properties.
• Generating API documentation.

Common XML Tags

4. Nested Comments

C# does not support nested /* … */ comments. However, you can nest // inside multi-line comments.

Incorrect (Will Cause Error)

/*
This is a multi-line comment.
/* This is a nested comment */
This will cause an error.
*/

Correct Way

/*
This is a multi-line comment.
// This is a single-line comment inside a multi-line comment
More text here.
*/

5. Best Practices for Using Comments

Write meaningful comments

// Calculates the total price including tax
double totalPrice = price * 1.08;

Avoid obvious comments

// Assigns 10 to x
int x = 10;

Use comments to explain complex logic

// Converts temperature from Celsius to Fahrenheit using the formula
double fahrenheit = (celsius * 9 / 5) + 32;

Use XML comments for public APIs

/// <summary>
/// Gets the full name of a person.
/// </summary>
public string GetFullName() {
    return firstName + " " + lastName;
}

Avoid excessive commenting

// Declare an integer variable
int age = 25; 
// Assign value 25 to the variable age

6. When to Use Comments

Document complex algorithms
Clarify the purpose of functions
Describe assumptions and constraints
Explain non-intuitive code
Provide usage examples for APIs

Do not state the obvious
Do not use comments as a replacement for clear code

7. Commenting Out Large Code Blocks

Instead of manually commenting out lines, use region directives.

Example: Using #region and #endregion

#region Temporary Code
/*
Console.WriteLine("This is a test");
Console.WriteLine("This code is disabled");
*/
#endregion

8. Generating Documentation from XML Comments

C# allows generating documentation files from XML comments.

Steps:

1. Write XML comments using ///.
2. Compile the code with csc /doc:MyDocumentation.xml MyProgram.cs.
3. Open the generated MyDocumentation.xml.

Conclusion

• Single-line comments (//) are for short notes.
• Multi-line comments (/* … */) are for large blocks.
• XML comments (///) document code for API documentation.
• Good comments explain why, not what.
• Use comments wisely to improve readability and maintainability.