C# Comments Tutorial

In this tutorial we learn how comments help us document our code. We learn how to write single and multi-line comments as well as XML documentation.

Here's a table of contents of what you'll learn in this lesson:
(click on a link to skip to its section)

Let's jump right in.

What is a comment

A comment is a way for a programmer to document a program and to enhance its readability. Essentially you’re making notes alongside your code.

All the comments in a file are removed at compile time meaning that when you build the project, the compiler goes through the code and removes all the comments that you made.

Why do we want to use comments

Normally we don’t, code should be clearly written so that it’s obvious as to what it does. That said, there are reasons for commenting your code:

  • When learning C programming it’s useful to comment most of what you’re doing, this helps you understand code easier because you’re not used to the syntax yet. We recommend that you comment your code as extensively as you like while learning to program in C# or any other language.
  • When using an external library it may be useful to comment what certain things do so you don’t have to go to the library or its documentation to look it up in the future.
  • A piece of code may interact with other pieces in such a way that it doesn’t seem obvious as to what it does at first glance, commenting allows you to quickly see what a piece of code is for.
  • When working with other programmers it’s a good idea to comment code so that they can quickly understand what a piece of code is for or what it’s doing.
  • Sometimes you want to temporarily remove a piece of code to try something different or see if a piece of code is causing an error or a bug.

Comment Syntax

C# provides us with two types of comments:

  • Single line comments
  • Multi-line comments

Learn the syntax for both comment types below.

Single line comment

A single line comment is written by using two forward slashes // in front of it. Anything following it on that specific line is a comment.

The IDE will usually color these differently as a way for you to visually distinguish between code and comments.

Example:
 // This is a single line comment

Single line comments can be written after some code but still on the same line.

Example:
 const float PI = 3.14; // Well, technically 3.14159265359 etc.

If a single line comment is made in front of any code, the line of code will not work as the compiler will throw it away when building the project.

Example:
 // const float PI = 3.14;

In the example above, we won’t have access to PI anymore, and any code that relies on it won’t work.

Multi line comment (Comment block)

A multi-line comment has a starting point and an ending point, anything in between these points will be considered a comment.

The starting point is denoted by a forward slash and an asterisk immediately after it /*. The ending point is denoted by an asterisk and a forward slash immediately after it */.

Example:
/*
This is a comment that spans over
multiple lines and can hold any
amount of code
*/
Example: alternative multi-line-comment
/* Some IDE's will automatically
 * format a multi-line comment
 * to look like this, don't panic
 * it's still treated as a comment
 */

Multi-line comments can be used in-line as well, meaning they can be used in a single line.

Example:
/* This is a multi-line comment on a single line, it's usefull when you want to comment in between code in a line */

for(int i = 0; i < 10 /* comment inside other code */; i++)

Typically you won’t see many multi-line comments as programmers tend to write multiple single line comments instead.

Example:
// This is a single line comment
// spanning multiple lines and
// is a valid way of commenting

for(int i = 0; i < 10 ; i++) // we can just comment after the code, no need to go in-between

XML Documentation

Visual Studio can help you document code elements such as classes and methods, by automatically generating the standard XML documentation comment structure. XML documentation is more in-depth than a normal comment.

As an example, let’s say we have the following method:

Example:
static int SomeMethod(int param1)
{
    return param1;
}

We can place our text cursor above the element we want to document and type ///

Example:
///
static int SomeMethod(int param1)
{
    return param1;
}

Visual Studio will then automatically generate an XML Comment for us.

Example:
/// <summary>
///
/// </summary>
/// <param name="param1"></param>
/// <returns></returns>
static int SomeMethod(int param1)
{
    return param1;
}

Alternatively we can place our text cursor above the element we want to document and:

  • Right-click > Snippet > Insert Comment
  • Go to the Edit > IntelliSense > Insert Comment

For more information on xml-documentation features, visit the official Microsoft C# documentationOpens up in a new page .

Summary: Points to remember

  • Commenting is a way for developers to document their code.
    • A single line comment is prefixed with two forward slashes // and will only be considered a comment on that line
    • A multi-line comment can span many lines, and is wrapped between /* and */.
  • XML documentation is a more in-depth form of commenting and can be generated by:
    • Hovering the cursor above the element and typing ///
    • Right-click, select Snippet > Insert Comment.
    • Go to Edit > Intellisense > Insert Comment.