.NET 1.1+

C# Comments

by Richard Carr, published at http://www.blackwasp.co.uk/CSharpComments.aspx

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 contains information that a programmer wants to add to describe the program. Comments are marked with special characters that indicate that they should be ignored by the compiler. They have no effect on the final software.

When to Comment

Comments can be used for many reasons. It is possible 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. They may describe what the routine is supposed to do and what information is returned on completion.
• Complicated Operations. Any implemented business rule that is not immediately understandable should include a comment explaining the purpose of the operation. However, if the code is unnecessarily complex, rather than the business rule being unusual, you should refactor your code to make it easier to read. Comments are not an alternative to high quality code.
• 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. You should also consider using a version control system to help manage changes.

How to Comment

Now that we have investigated why and what to comment, we need to know how to comment. There are three types of comment that C# can include. They 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 a double forward slash, (//). Any text or code following the double slash is ignored during compilation.

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

Trailing Comments

A trailing comment is a variation of the single line comment. In this case, the double slash appears at the end of a line. Any code before the comment symbol is treated as a part of the program. 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. It is useful for commenting out large blocks of code.

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