Commenting Best Practices in C#

Documenting your code – also known as commenting – is a very important, yet often overlooked, aspect of software development that a lot of coders tend to overlook. Some programmers are diligent about commenting their code, while others will leave entire blocks with little to no comments. Perhaps even worse, some developers do not know the difference between good commenting and bad commenting, such as leaving smelly or W.E.T. comments.

This C# programming guide looks at not only how to write comments in C#, but also discusses the best practices for leaving comments in your code.

Read: Tips for Writing Clean C# Code

How to Write Comments in C#

Below we discuss the different types of comments C# has to offer and how to write them to better document your C# code. We start off with the most common type: single-line comments.

Single Line Comments in C#

Writing single-line comments in C# is fairly simple. You start your comments by using double forward-slashes or //. When C# sees // on a line, it ignores everything after those double-slashes until the end of the line. This is an important distinction, as any text you write on the following line that is not preceded by double-slashes will be treated as code and – if it isn’t – will cause errors in your application.

The following code shows how to write single-line comments in C#:

// This is a single line comment
// powerLevel represents the super hero's power level and ranking
powerLevel = 90;

Console.WriteLine("The Hero has the following power level:");
Console.WriteLine(powerLevel);

Another type of single-line comment you can create is known as an inline comment. Inline comments are sometimes called trailing comments as well. This is because this type of comment follows – or trails – a portion of code and resides on the same line. Here is an example of how to write inline comments in C#:

powerLevel = 90;   // Represents a hero's powerlevel

As you can see in the above example, the inline comment comes after the code but does not carry over to the next line. A quick note about inline or trailing comments – it is always best to avoid using this type of comment unless it is absolutely necessary, as they can make your code difficult to read and affect code readability.

Read: Working with Strings in C#

Multi-Line Comments in C#

Technically, you can write multi-line comments – that is comments that span more than one line – in C# by just using a bunch of single-line comments, like so:

//This is a comment
//This is a comment on another line
//Here is another comment!

powerLevel = 90;

While that is perfectly valid, true multi-line comments are written in C# by starting them with /* and ending with */ on the same or a different line. The text between the /* and */ is your comment and is ignored by C#. Here is how to write a multi-line comment in C#:

/* This is the start of our multi line comment
powerLevel represents the super hero's power level and ranking
We will use it to calculate how strong a hero is
This is the end of our multi line comment */

powerLevel = 90;

Console.WriteLine("The Hero has the following power level:");
Console.WriteLine(powerLevel);

Read: Working with Mathematical Operators in C#

Best Practices for C# Commenting

Below are some of the best practices for writing comments in C#:

  • Only use comments for code snippets that are hard to understand or need clarification.
  • Keep comments simple: remember their purpose. They should precisely describe what a portion of code does.
  • Don’t be rude or mean in your comments. Be professional.
  • If you change a portion of code, be certain to change the comments to!
  • If you have multiline comments or multiple inline comments, make sure they are aligned for easier readability.
  • Keep comment lines short. Use multiple lines if necessary versus cramming them all on one line.
  • Use the same style of comments as the rest of your development team or that you use in your entire application.
  • Avoid W.E.T. comments or comments that waste everyone’s time. Don’t explain something that is obvious.
  • Avoid smelly comments. Smelly comments are comments that attempt to justify or explain bad code. Rewrite your code instead. One final note about C# comments – they are not only used to tell yourself – or other developers – what your code was intended to do.

Comments can also be used to troubleshoot code and find errors. You can use comments to comment out lines of code so that you can make sure those parts of code are not the culprit causing problems. Just remember to remove the comment from the code once you are satisfied that particular line or block of code is causing the issues in your application.

Read more C# programming tutorials and C# developer tool reviews.

More by Author

Get the Free Newsletter!

Subscribe to Developer Insider for top news, trends & analysis

Must Read