Code Comments – When, why, and better programming.

When programming, when and how should we code comment? Is there best practices? Are there good things to comment? How about bad things? Well lets discuss.

First off, you if have not read about code my C# code comments be sure to check it out here. Code comments are something that should be done correctly, regardless of what programming language you are working on.

Contrary to popular belief, writing code comments is not always a good thing. The rule of thumb is that the code should be self documenting. This means that all variables, methods, functions are meaningful.

So what are we talking about? Lets say we have the following code snippet: var btnDm = new Button(); Does that explain what exactly is going on? Sort of. We are creating a new variable called btnDm that is a new Button() object. Now if we explained this with a code comment we would know what were doing with this line of code; However, if we use this btnDm in a later place of code, we may end up a bit more confused (especially with the variable name not being really descriptive). The real way we should be doing this is simple. Button buttonDissmiss = new Button();

Having the types be referred to by the class instead of being implicitly typed local variables will help with code being more readable. This also allows code to be seen as what it is instead of being dissociated by others of the actual class type.

Secondly we have the variable name. Earlier we used btnDm, and it was typed up using a semi Hungarian style naming convention. The problem with this is most of the time, knowing what these variables are for are not easily understood. Switching this name to buttonDissmiss gave a better understanding of what this button is, and will be able to be understood in other area’s of the code. Think if you tried to use this button in another class or 50+ lines later, it would be clear to know what it is for.

So now about code comments. With the first example, we could of put the code comment above that line and had something like:

// create a new dissmiss button for ....
var btnDm = new Button();

The biggest issue with this is we would not see that code comment in later references. By switching to use a more readable and understandable code line, this became clear and made a code comment not needed.

So when should i code comment?

Code comments are necessary for some items and should be done as much as possible. Seems like a contradiction to what was explained earlier, but is actually important. The main places to worry about code comments are area’s where any documentation is generated such as with API’s for swagger / openapi. Even not when using documentation generation, having the code comments for API’s is always important.

Example:

        /// <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);
        }

When you know that something is needed in the future for a section of code adding a comment is not a bad thing to do. Generally having the code marked with a key word such as “TODO:” will help with this task. Making sure to follow up with them as well as remove once the to do item has been finished.

When a method is created to fix a defect, it is neither a bad idea nor good idea to add a comment with a ticket number (such as Jira, Github, TFS). This is really determined by either your personal preference or your team policy.

Finally, if a method has something rather complex, the idea of adding a code comment is again neither a good nor bad thing to do. Typically if this is truly complex and took some research to work on, having some comments to document how and why (as well as any links to stack-overflow etc) is not a bad idea. The other factor of this is to try and look at the block of code to determine if the code itself is complex due to a lot of non straight forward programming. The question should come into your mind of weather this could be broken down into other methods or other ways of simplification.

Generally having your methods short, sweet, and to the point. Keeping the motto “KISS” in mind.

When working with code, just remember to take a look at what you are doing and try to make it self documenting. Self documenting code is greater than code comments. What are your thoughts on code comments?

Leave a Reply

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