.NET 1.1+

C# Comments

The second part of the C# Fundamentals tutorial looks at adding comments or remarks in the program code. Commenting is essential in team-based development or when maintaining code that is revisited only periodically.

What is a Comment?

A comment, also known as a remark, can contain any information that a programmer wants to add to describe the program. The comment itself is marked with special characters so that it is completely ignored by the compiler and has no effect on the final software.

Why Comment?

A question asked frequently by the novice programmer is "Why should I comment my code at all?" Usually a statement follows to the effect that commenting takes up too much time or that the comments will be added once the project is finished.

These arguments are fundamentally flawed. Commenting takes some time in physically typing the comment. However, when debugging anything more than the simplest program, working out what you meant (or worse, what your colleague meant) when originally writing the code will take longer without the comments. Adding the comments at the end of the project is misguided for similar reasons.

I myself comment first and add code later. The comments remind me of what the code should be doing as well as acting as a handy reminder when I come to debug.

When to Comment

Comments can be used for many reasons. If is possible, however, to over-comment your code so you should ensure that your comments are useful. The following lists some items that are often commented:

• Methods. Comment may be added to methods, functions or sub-routines of a program. The comments may describe what the routine is supposed to do and what information is returned on completion of the method.
• Complicated Operations. Any operation that is not immediately understandable should include a comment explaining the purpose of the operation and how it undertakes the task. However, you should also consider reworking your code to make it easier to read.
• Code Files. Each file or program can include a comment as a header detailing the author of the program, the date it was created and the version number. Other notes may be added such as a version history or any pre-requisites for the operation of the program.
• Code Changes. In a team environment it can be useful to add a comment whenever some code is modified. This may include the name of the programmer making the change, the software version number and date. One or more lines of code may be marked as a comment to remove it from the compiled program without removing it from the source code. This is called commenting out the code.

How to Comment

Now that we have investigated why to comment and what to comment, we need to know how to comment. There are three types of comment that C# can include. These are single line, trailing and multi-line comments.

Single Line Comments

The simplest form of comment in C# is the single line comment. The line is started with the single line comment symbol, which is a double forward slash, (//). Any text or code following the double slash is ignored during compilation of the program.

// This is a comment and the next line is commented out
// Console.WriteLine("Hello, World");

Trailing Comments

A trailing comment is a simple variant on the single line comment. In this case, the double slash appears at the end of a line of code. Any code before the comment symbol is treated as a part of the program. Any code after the symbol is the comment.

Console.WriteLine("Hello, World");   // Output a greeting

Multi-Line Comments

The final type of comment is the multi-line comment. This includes a start symbol, (/*) and an end symbol, (*/). Any information between the two symbols is treated as a comment. This may span multiple lines and can also be used to comment out entire blocks of code.

/* This is a multi-line comment
   and continues until the end
   of comment symbol is reached */