C# Code Comments

Code comments are an essential part of programming. However, there are good and bad times to write a code comment. We will go into details and how to write code comments. The good, the bad and the ugly of all of it.

First off, there is two ways to write code comments. There is single line comments and multi line comments.

To write a single line code comment, you will start the line off with “//”. The double slashes will result in the line becoming a commented line. Example:

//This is a single line code comment.

To write a multi line code comment, you would start with “/*” and end with “*/”. This would look like:

/*
making a code comment.
some fantastic comment here.
yay!
*/

When to code comment

Code comments are something that should be used, however should be used in a meaningful matter. There is such a thing as too much code comments.

Everyone has their own preference for when and what to code comment. A good rule of thumb is to write code comments that are meaningful and help with documentation. Generally you want to write code that is self documenting. Meaning that the code you write is easy to read and easy to understand. However, there are times where adding a little code comment can be a helpful tool.

A good example of a code comment would be:

// TODO: Update to give more information such as what information was received
Console.WriteLine("Received information... ");

On the above example, a code comment was made that more information should be added to this code. Marking a code comment with “TODO:” is a good marker for indication of items that should be updated or changed later. These are also easily searchable.

When working with WebAPI’s, adding a comment to the top of the method is a great thing to do. You can easily type three slashes “///” in visual studio above the method and it will generate a code comment template for the api for you. These should always be done. Example:

        /// <summary>
        /// 
        /// </summary>
        /// <param name="name"></param>
        /// <returns></returns>
        [HttpGet("[action]/{name}"]
        public IActionResult GetDataByName(string name)
        {
            UserData data = _context.ByName(name);
            if(data == null)
            {
                return BadRequest("no data found");
            }
            return Ok(data);
        }

Note that in the above code block, the summary, name, and return are able to be filled out by you. So this could end up looking like:

        /// <summary>
        /// Get user data by username
        /// </summary>
        /// <param name="name">string</param>
        /// <returns>IActionResult</returns>
        [HttpGet("[action]/{name}"]
        public IActionResult GetDataByName(string name)
        {
           UserData data = _context.ByName(name);
            if(data == null)
            {
                return BadRequest("no data found");
            }
            return Ok(data);
        }

Leave a Reply

Your email address will not be published. Required fields are marked *