Understanding C# Comments & It’s Types With Code Examples

C# Comments

Comments are annotations or illustrative statements in the code of C# that the compiler ignores. Their main objective is to make some sections of the code more clear and intelligible for developers by providing clarification or explanation. This is especially crucial for cooperation and program maintenance.

Two primary comment kinds as well as a unique type for documentation are supported by C#:

Single-Line Comments

Two forward slashes (//) mark the start of a single-line comment, which continues to the end of the line.

Code Example:

using System;
namespace MyApplication
{
    class Program
    {
        static void Main(string[] args)
        {
            // This is a single-line comment. It explains the next line of code.
            System.Console.WriteLine("Hello, C#!"); // Another single-line comment, inline.
        }
    }
}

Output

Hello, C#!

Both of the lines in this example that begin with // are comments and will not be compiled.

Multi-Line (Delimited) Comments

Delimited comments, sometimes referred to as multi-line comments, begin with /* and finish with */. Any text that appears between these symbols is regarded as a comment; if necessary, it may extend across several lines.

Code Example:

using System;
namespace MyApplication
{
    class Program
    {
        static void Main(string[] args)
        {
            /* 
             * This is a multi-line comment.
             * It can span across several lines, providing a detailed description
             * of a code block or section.
             */
            System.Console.WriteLine("Hello, World!");
        }
    }
}

Output

Hello, World!

When explaining longer code segments or temporarily turning off code blocks for testing, this kind of comment is helpful.

XML Documentation Comments

A unique kind of comment called an XML documentation comment is used to create API documentation straight. They have XML tags that describe classes, methods, parameters, return values, and other things, and they start with three forward slashes (///).

The C# compiler interprets these XML tags and generates a distinct XML documentation file when compiled with the /doc option. Various tools, including Visual Studio’s IntelliSense, can then use this file to give developers real-time assistance and information.

Common XML Documentation Tags and their purpose:

<summary>: Gives a brief explanation of a member or type.

<param name="name">: Explains a parameter in the procedure.

<returns>: Explains a method’s return value.

<example>: Gives an example of how to utilize a member or method; it frequently includes <code> tags.

<code>: Identifies several lines of text in an example as code.

<c>: Designates a single line of text that is inline as code.

<exception cref="member">: Records any exceptions that a method may make.

<remarks>: Enhances the summary by offering more details on a category.

<see cref="member">: Makes a link to another code element inline.

<seealso cref="member">: Contains text that links to relevant code elements in a “See Also” section.

Code Example of XML Documentation Comments:

using System;
/// <summary>
/// Represents a simple calculator that performs basic arithmetic operations.
/// This class demonstrates the use of XML documentation comments.
/// </summary>
/// <remarks>
/// Author: AI Assistant
/// Version: 1.0 (October 26, 2023)
/// </remarks>
public class SimpleCalculator
{
    /// <summary>
    /// Adds two integer numbers together.
    /// </summary>
    /// <param name="number1">The first integer number.</param>
    /// <param name="number2">The second integer number.</param>
    /// <returns>The sum of the two numbers.</returns>
    /// <example>
    /// This sample shows how to call the <c>Add</c> method.
    /// <code>
    /// int result = SimpleCalculator.Add(5, 3);
    /// Console.WriteLine(result); // Output: 8
    /// </code>
    /// </example>
    /// <exception cref="System.OverflowException">Thrown if the sum exceeds the maximum integer value.</exception>
    public static int Add(int number1, int number2)
    {
        checked // Enable overflow checking 
        {
            return number1 + number2;
        }
    }
    /// <summary>
    /// Subtracts the second number from the first.
    /// </summary>
    /// <param name="a">The first number (minuend).</param>
    /// <param name="b">The second number (subtrahend).</param>
    /// <returns>The difference between a and b.</returns>
    public static int Subtract(int a, int b)
    {
        return a - b;
    }
    static void Main(string[] args)
    {
        int sum = Add(10, 5);
        Console.WriteLine($"The sum is: {sum}");
        int difference = Subtract(10, 5);
        Console.WriteLine($"The difference is: {difference}");
    }
}

Output

The sum is: 15
The difference is: 5

Self-documenting code, or code that is understandable and clear without comments, is regarded as the ideal practice, even if comments are essential for code comprehension. Rather than merely restating what the code does, comments should enhance well-written code by elucidating obscure details and outlining overarching goals.