//) in front of the text./* this is a comment */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).
A comment is merely text that you place in and around your code that is meant for you and other programmers. The computer completely ignores them.
Very small programs are easily understood by simply looking at the code.
For example, Console.WriteLine("Hello World!"); is easy to understand at a glance.
But as your programs grow in size, it becomes less obvious what it does at a glance.
It is a good idea–and an important skill to have–to make code “self-documenting.” That is, to the extent possible, you should make choices in your code that ensure that it is as easy as possible for somebody to come along and read the code and make sense of it. This may come as a surprise, but you will spend far more time reading your code than you will writing it. So it is critical to ensure that the code makes sense even after you’ve been away from it for a few weeks (or years).
There are a lot of things you can do in your code to help with that goal. While programming, you will give names to most things you create. Picking a descriptive name is a powerful tool for helping readers understand it. Good use of whitespace (indentation, blank lines, etc.) is another indispensable tool. Using whitespace appropriately can reveal the structure of the code better.
But not everything that matters can be clearly conveyed in the actual code itself.
For example, when you first look at a section of code, it is sometimes useful to have a high-level description of the general approach or strategy. Good names help, but they may not be enough.
Similarly, if you have a need to explain why the code works like it does–the code itself can’t tell that story.
Comments allow us to inject bits of extra information–a hint of “story time”–into the code to convey things that aren’t immediately evident by looking at the raw code.
C# gives you three different ways to define comments in your code.
//The first style is with two forward slashes: //.
Everything after a // on a line is considered a comment, and is ignored by the compiler.
For example:
// This is a comment.
Console.WriteLine("Hello World!");
A comment does not need to be on its own line. It can share a line with other code. But once the comment starts, it continues to the end of the line:
Console.WriteLine("Hello World!"); // This is also a comment.
/* and */The second style is with a /* and a */.
Anything between those is a comment.
This style allows you to put a comment in the middle of the line if you want:
Console.WriteLine(/* This is a comment. */"Hi!");
This style lets you span multiple lines with a single comment:
/* This is a multi-line comment.
It spans multiple lines.
Isn't it neat? */
Of course, you can spread a comment over multiple lines with the double-slash style as well by putting // at the start of each line:
// This is a multi-line comment.
// It spans multiple lines.
// Isn't it neat?
Between the two styles, I see C# programmers using // more often.
There are fans of both styles.
I’ll generally use the double-slash style in these tutorials, but use whichever version you like better.
(And you should experiment with both to see what you like better.)
///The third style of comment is a minor variation on the first. It is a triple-slash comment, or more formally, an XML Documentation Comment. It is done by putting three forward slashes together, but otherwise works like a double slash comment.
/// <summary>
/// Runs the program.
/// </summary>
public class Program
{
// ...
}
These comments are not meant to be applied generally, anywhere and everywhere. Instead, they’re used to provide documentation about the usage of specific code elements, such as classes and methods.
Documentation tools, including Visual Studio itself, will scrape these (and only these) comments to generate documentation for code you write.
(It uses the XML tags it finds, like <summary>, to know how to format and organize the content it finds in the comment.)
We won’t worry about this third style very much in this tutorial set. It is more useful if you are building code meant to be reused across many projects, or in a very large project. But you will bump into them from time to time, and it is useful to have a notion of what they are.
The mechanics of making a comment is easy. Knowing what places deserve comments and what they should say is harder.
Start by writing comments at about the same time as you write the code you are commenting on. If you come back to it two weeks later, you won’t remember enough details to add helpful comments.
You also don’t want to write comments that add little value. The comment below adds nothing the code doesn’t already say:
// Writes out "Hello World!"
Console.WriteLine("Hello World!");
Everything the comment says, we already knew.
In truth, this one line probably doesn’t demand a comment at all. But the version below adds an explanation or justification for the code, which is far more meaningful:
// Hello World is the traditional first program in any language we learn.
Console.WriteLine("Hello World!");
score = 0;
It is possible to add too many comments. You want to keep them brief.
I’d dare say that comments that are wrong are actually far worse than having no comments at all. That means that when you add comments, you’re committing to maintaining them for however long they’re around for. That’s an extra burden for you.
But the right comments add important value that can’t be gained through other means, and are well worth it. Just keep the time you’ll have to spend maintaining the comment in mind as you write it.
The right comment can save you hours of studying the code, trying to understand it.
You’ll find the right balance as you gain experience. For now, I’d suggest it is better to err on the side of too many comments than not enough.
Because the compiler ignores comments, they can be used to temporarily ignore a section of code. For example:
Console.WriteLine("They're taking the Hobbits");
// Console.WriteLine("to Isengard.");
Console.WriteLine("to Fangorn Forest.");
By putting a comment on the second line, it will be ignored, even though the comment looks like it could be code.
Programmers use this trick to temporarily ignore the code while they’re experimenting and exploring.
Just don’t leave commented-out code hanging around forever. Either delete the commented out code entirely or strip out the comments and start using it again. Leaving large blocks commented out for the long term clutters the code and makes it hard to keep track of what’s going on.