C# Clean Code: Commenting Conventions

Have you ever wondered if comments are worth including in your code? While they aren't used by the compiler to execute your application, well-written comments can simplify code maintenance, make debugging faster, and provide clarity for other developers, especially when creating libraries or reusable code.

In this article, we’ll explore how to write clear, useful comments in C#, highlight best practices, and discuss when to use XML documentation comments.

1. Why Use Comments?

Comments serve as a guide to understanding code behavior. They should provide context, describe complex logic, and explain assumptions. Comments are particularly helpful when revisiting old code, allowing you (or another developer) to grasp the purpose and functionality quickly.

2. Basic Conventions for Comments

When writing comments in C#, follow these simple conventions:

• Place comments on separate lines, not at the end of a line of code.
• Start the comment text with an uppercase letter, treating it like a normal sentence.
• End the comment with a period for consistency.
• Insert one space between the comment delimiter (//) and the comment text.

Example

// This method calculates the sum of two numbers.
public int Add(int a, int b)
{
    return a + b;
}

3. Using XML Documentation Comments

XML documentation comments are used to create structured and detailed documentation for your code. They are particularly useful for:

• Providing summaries for classes, methods, or properties.
• Describing parameters and return values.
• Generating API documentation in formats like PDF or HTML.

To add XML comments in Visual Studio, type three forward slashes (///). This shortcut generates an empty XML comment snippet that includes placeholders for the summary, parameters, and return value.

Example

/// <summary>
/// Calculates the sum of two integers.
/// </summary>
/// <param name="a">The first integer.</param>
/// <param name="b">The second integer.</param>
/// <returns>The sum of two integers.</returns>
public int Add(int a, int b)
{
    return a + b;
}

The XML file generated during compilation contains structured data representing these comments, making it easier to generate human-readable documentation.

4. Avoiding Common Comment Mistakes

While comments are meant to clarify code, they can sometimes add confusion. Here’s what to avoid:

• Blocks of asterisks: While tempting for separation, they make code harder to read.
• Humorous or unclear comments: Comments should be informative, not amusing.
• Ticket or issue references: Avoid adding ticket numbers directly in comments, as the code evolves and the context may change.

Example of Improving Comments

Before:

/******************/
/* Calculate sum. */
/******************/
public int Add(int a, int b)
{
    return a + b; // Returns sum
}

After:

/// <summary>
/// Adds two integers.
/// </summary>
/// <param name="a">First integer.</param>
/// <param name="b">Second integer.</param>
/// <returns>The sum of two integers.</returns>
public int Add(int a, int b)
{
    return a + b;
}

5. Final Tips for Writing Comments

• Keep comments useful and relevant. Remember, comments are meant to help the next developer (or your future self) understand the code.
• Use comments to clarify, not complicate. Code should be self-explanatory, with comments providing additional context where needed.

By following these conventions, you’ll make your C# code more maintainable and accessible to other developers. Start adding comments that matter and make your code shine!