3 minutes

This question is recurrent when you develop a software, following DevOps method or not. A comment will help you to make your code easily understandable by any developer,  while keeping it easily readable. And if you don’t use those comments parsimoniously, it can turn into a nightmare in a blink of an eye! That’s why we summed up all our good practices regarding comments in code 👇🏻

Guideline to write a good comment

We will share with you our guidelines to write good comments in your code. And of course, you can adapt them in order to create your own rules and share them with your team.

Rule n°1: good comments say what the code can’t

It could seem obvious: your comment add information that your code can’t display. It can be a specification on why you are using a specific function, a detail on the way it was built… 

But be careful! Having comments in your code doesn’t mean you can have a dirty and unclear code. Adding information to guide the reviewer is a good thing, but the basis of your code should be clear. For example, think to give your function and variable a proper name.

See below an example where the comment doesn’t explain what the code written actually does.👇🏻

Comment in code: a bad example

And there is a good example, with comments adding information to the code. 👇🏻

Comment in code: a good example

Rule n°2: If you can’t write a clear comment, there may be a problem with the code

A comment adds context, but shouldn’t repeat any information you already have in your code! Of course, adding details on why you set up your variables a certain way is useful. But if written properly, your code should be self-explanatory. 

Putting it another way: you don’t need to add a comment to explain what your function is doing if the name of the function is clear. If you feel like the person that will read your code won’t understand your function, maybe you should look at your code and how you write it rather than adding comments like crazy.

See below this example: if the function is implemented properly, the comment isn’t really useful! 👇🏻

Comment in code: a bad example

This was a bad example, see below a good one.

Comment in code: a good example

Rule n°3: a comment isn’t a to-do list

Debugging your code is a good thing! Of course, sometime it takes more time to find what doesn’t work than to correct it. But it doesn’t mean that you can only write in your code what is broken and never correct it!

Of course, when you are writing your code, you can use comment to know what you have to do, what you should repair or everything that can help you. But those comments should disappear before you share your code and push it in your final product.

See here something you shouldn’t do 👇🏻

Comment in code: a bad example

And here what you should do 👇🏻

Comment in code: a good example

When writing a comment?

Writing comments in code is not an obligation. In fact, you can find a lot of articles on the web giving pros and cons for both practices. The only thing we advise you if you decide to add comments in your development is to be organized and write them judiciously to add value to your code and not make it more complicated.

Writing comments: a team work

The most effective way to implement guidelines in your team is to define with all your team members which rules you need to follow. You can write with them the guidelines, and include a line at the end of your Definition of Done to make sure everyone follows them!