C# Comments: How and Why
Tutorials SmallArrow.png C# Tutorials SmallArrow.png C# Comments: How and Why Previous Next

C# Comments: How and Why

Crash Course

  • Comments are ways for you to add text for other people (and yourself) to read that the computer ignores.
  • Comments are made by putting two slashes ("//") in front of the text.
  • Multi-line comments can also be made by surrounding it with asterisks and slashes like this: /* this is a comment */

Introduction

In this short tutorial, we'll cover the basics of comments. We'll look at what they are, why you should use them, and how to do them (in three different ways). Comments are an extremely useful tool, but I also don't want to overemphasize them. You'll write a lot more "normal" code than you do comments. But they're convenient for leaving notes for yourself or other programmers in the code.

Importantly, I want to introduce them now because I plan on using them as a tool for annotating code samples in the rest of these tutorials.

What is a Comment?

At its core, a comment is text put into the code for a human to read that is completely ignored by the computer.

Why Should I Use Comments?

There are a handful of uses for comments.

1. You can leave a note that summarizes what a chunk of code does. This can sometimes jog your memory about what it does or teach you about code that you haven't used before.
2. You can explain things about the code that are not evident from simply inspecting the code, such as why you did what you did.
3. You can turn otherwise real code into a comment to temporarily disable it. This is referred to as "commenting out" the code. (Just don't leave commented-out code hanging around forever. Either delete the unused code or remove the comments to bring it back into use.)

While you should make every reasonable effort to make your code as readable as possible without comments, you should also add appropriate comments to summarize and elaborate to assist with helping you or others understand what it does and why it was done that way. When you've been away from some code for a few weeks, you won't remember what it did, and comments can speed up the process of figuring it out immensely.

How to Make Comments in C#

There are three basic ways to make comments in C#. For now, we'll only consider two of them because the third applies only to things that we haven't looked at yet and won't for a while.

The first way to create a comment is to start a line with two slashes: //. Anything on the line following the two slashes will be ignored by the computer. In Visual Studio (and other IDEs), the comments change color (in this case, to green) to indicate that the rest of the line is a comment.

For example:

// This is a comment where I can describe what happens next...
Console.WriteLine("Hello, World!");

Using this same thing, you can also start a comment on the same line as some code, but everything after the two slashes will be ignored.

Console.WriteLine("Hello World!"); // This is also a comment.

A second method for creating comments is to use the slash and asterisk combined surrounding the comment:

Console.WriteLine("Hi!"); /* This is a comment that ends here... */ Console.WriteLine("More stuff can go after the comment, here.");

This can be used to make multi-line comments like this:

/* This is a multi-line comment.
    It spans multiple lines.
    Isn't it neat? */

Of course, you can do multi-line comments with the two slashes as well, it just has to be done like this:

//  This is a multi-line comment.
//  It spans multiple lines.
//  Isn't it neat?

In fact, most C# programmers prefer using the two slashes all the time, and the slash/asterisk combination is only there because it is a holdover from the C programming language.

There's another type of comment you can use that starts with three slashes ("///"). This is used for automatically creating technical documentation for your code, but it only really works in certain places, which we haven't really gotten to yet. I'll describe the three slash comments in more detail when we do. (FYI, this kind of comment is called an XML documentation comment.)

How to Make Good Comments

Commenting your code is easy; making good comments is a little trickier. For starters, you should comment your code soon after you write it, rather than much later. A few days or a weekend away from the code, and you may no longer really remember what you were doing with it. (Trust me, it happens!)

Second, write comments that add value to the code. Here's a bad example of a comment for a line of code:

// Sets the score to 0
score = 0;

Everything the comment says, we already knew. Here's a better example.

//Resets the score to 0 because the game is starting over.
score = 0;

You don't need a comment for every line of code, but having one for every section of related code is helpful. I've seen the occasional chunk of code that is over-commented, but the dangers of over-commenting code matter significantly less than the dangers of under-commented or uncommented code, and most new programmers trend toward too few, rather than too many.

What's Next?

With a basic "Hello World" example and some basic guidelines on commenting code under our belts, let's go on to our first real programming topic: variables.

Tutorials SmallArrow.png C# Tutorials SmallArrow.png C# Comments: How and Why Previous Next