The Best Practices For Writing Comments in Code

Is there a correct way to write comments in code?

“Good code is self-documenting.”

On the subject of comments, all programmers can be roughly divided into two categories:

• clean code needs no comments
• professional programming means commenting

There are some programmers who say that comments do more harm than good, but let’s not go there today. There are pros and cons of each approach but if you are a beginner, it’s safer for you to become a part of the second camp. At least, for now. Later, you might decide that your code is so awesome it doesn’t need any comments, but when you are just starting, avoiding comments can be a fatal mistake. And here’s why.

Why comments are crucial

There are three main reasons for writing comments in your code:

• communication
• clarity
• explanation

And only one downside: time spent writing them. Well, and maybe space they take. But these are not critical issues. If you are working in VS Code, you can use autocompletion and collapse the comments. Even if you are using something like Vim, it’s still not a big issue.