Comments In C#

February 19, 2016

Comment is a text description of the program logic i.e. what the program does. Comments are ignored by the compiler when you build the program. It is considered to be a good programming practice.

We programmers tend to forget what certain lines of code does when we revisit our code again after several days and it becomes easy for us and other programmers to understand the code if we write proper comments. Comments are also used to produce automatic documentation of the source code. There are various generators available that can generate the documentation for you. Don't write comments for every single thing. Write where you think it is needed and logical.

3 Types Of Comments

1. // - Single Line Comments - Two forward slashes indicate all the text to the right of comment mark will be considered as comment until end of that line.

2. /* */ - This is multi line comments. When you want to comment multiple lines, use this style.

Single Line And Multi Line Comments

3. /// XML Comments - This type of comments are used for XML based documentation of your code. This describes what this class does or what this particular method does or what types of arguments are expected as input in the method etc. When you start typing /// (3 Forward Slashes), Visual Studio automatically completes that for you(Intellisense). Try typing ///, you will have a structure for your comments.

CheezyCode - XML Comments

What is the use of these XML Comments?

If you hover on the Console class, you will have a popup describing about the class or if you hover on the method WriteLine - it describes about the method (refer below screenshot). If you want this for your classes and methods, you can do this via XML Comments.

As shown above - how useful these xml comments are. Let's see how we can use them for our classes and methods. Type this code in Visual Studio.

using System;

/// <summary>
/// Comment About This Class - Why It Is Needed 
/// </summary>
class Program
{
    /// <summary>
    /// Application Starter Main Method
    /// </summary>
    /// <param name="args"></param>
    static void Main(String[] args)
    {
        Console.WriteLine("Explaining XML Comments");
        Calculator oCal = new Calculator();
    }
}

/// <summary>
/// Calculator Class For +-*/
/// </summary>
class Calculator
{
    /// <summary>
    /// This method adds two integer numbers and returns sum as an integer
    /// </summary>
    /// <param name="firstNumber">First integer to be provided as input</param>
    /// <param name="secondNumber">Second integer part of input</param>
    /// <returns></returns>
    public int AddNumbers(int firstNumber, int secondNumber)
    {
        return firstNumber + secondNumber;
    }
}

Here Calculator is our custom code - we have created this class or type (More about Classes in future posts). When you hover onto Calculator class on Line 15, XML comments will appear as popup. Same applies to Methods and its arguments. Refer screenshot below and XML Comments in the program for clarity.