The use of comments

During our work as software developers, we have seen and used comments many times. Usually, they are green lines of text telling us all kinds of things. The use of comments can be a bit tricky and during my time as a C# teacher I have answered this question many times: What is the use of comments?

There are many scenarios to think of where you might want to use comments. But to do it right is not that easy. The idea of using comments is to clarify or give information about code. Comments are not shown to the end users and are mostly used by developers. They don’t change the code and can’t be used to make code act differently. It’s purely for information purposes only.

A few scenarios where you want to use comments

These are just a few that come to mind. If I would combine that and use it in a class, it would look a bit like this:

Maybe I have gone berserk on this simple class, but trust me when I say this really happens. I actually saw something like this once:

I hope you agree with me that both examples are a bit exaggerated. The second method is totally unnecessary. It would be better to remove it and change the method that uses this comment.

The first example does have some valid comments. Like explaining what the method does or what (and why) certain actions are taken. But, in my opinion, it’s more comment than actual code. I like to see my code and not comments.

All the comments in the first example are easily fixed by using other tools and techniques. All the comments above a method or class, explaining the working of the code and contents, can be moved to a summary. And a summary can be moved to an interface.

The ‘ToDo’ is a bit different. If it’s just one I tend to just leave it there. But chances are you might forget it. Most of the time a ToDo is something small. Why not do it as soon as you are in the code? Most standard replies I get:

“It’s out of scope with my work item on the scrum board“

Then make another work item so you can fix it later. This way you will see it later on the board and even your team members can fix it.

If you write good code you don’t have to explain them. Take the following lines of the first example.

“Get the movie from the list by calling Get()”… Duh, I can see that on the next line. Code can be read as a language (hence programming language). If you write good code it’s self-explanatory. The same goes for the names of the methods: make them so others understand what the method is about.

If I would “fix” the first example it would look like this:

This feels good; I see code!

Imagine you create a library that will be used by other developers. It will contain some classes and methods. Each with its own functionality. But other developers don’t have access to the source code. So how do they know what the methods are about? Summaries.

I already mentioned them earlier and with the better version of the MovieService class (the one without the comments), I moved the descriptions of the methods and class to an interface. The interface looks like this:

Summaries are basically comments that can be used for documentation. If you compile this to a DLL and another developer uses that DLL he/she can see the summaries when initializing and using your class. Some applications can extract those summaries and generate some sort of PDF as a manual if you wrote the summaries correctly.

The only comment you could use is with unit testing. Here we use the so-called triple-A, which is not the roadside assistant. It stands for:

And also in that order. It means you define the area where you arrange the unit test (prepare everything), act on the actual code you want to test, and where you use assertions to check if the test was successful, or not.

The following example is a unit test used in the tutorial Azure Computer Vision — Convert image to text.

Here you can clearly see the different sections of the unit test.

Have you ever been in a store where they label everything like crazy? Imagine you see a strawberry and there is a label on it that says ‘Strawberry’? Sounds silly, right? Do not do unnecessary labeling.

Although it sounds logical, this happens a lot in code. If the name is correct you don’t have to explain it with a label or a comment. Let’s take a look at a method:

The name of the method doesn’t need an explanation, and yet it has one. I am in the MovieService class, which indicates all the methods in the class do something with movies. Delete indicates something will be deleted. Since I am still in the MovieService I can assume the delete will delete a movie. The comment “This deletes the movie” is totally worthless here.

If I would use this class and method somewhere in my application it looks like this:

Sometimes an explanation is needed. Take a look at the following code.

Now I am going to initialize and use it again:

I have no idea what this method does. Yeah, something with movies. But “MakeItHappen”? Make what happen? And what is variable? Oh, wait! It’s in the comment.

It would be better to give the method and the variable a better name so everyone knows.

Using unlogical names and a bad explanation in the comment or summary can be really disastrous. Before you know it people use something in a way they aren’t supposed to use.

It’s not that I hate comments, not at all. It’s just that if you are not careful your code - the thing you need the most - can be overrun by green lines. Most of the comments I have seen in my career are redundant or just meaningless (1 equals 1, so it’s true).

Related posts:

iceqbs- Innovative Consultants for End to End Quality Business Solution. Organizations who believe that “there is always a scope for improvement” grow exponentially. We, at iceqbs, help such…

Shopping UK will automatically categorise your list into aisles. This makes it easy to find things in the supermarket. The app has a built-in list of over 20,000 items, and it does a pretty good job…

It is indeed perplexing how a multi-cellular organism (like us) is able to create itself from a single cell. It’s curiously interesting to think about how cells are able to join together to create…