A good comment gives a good information

IIntroduction

A comment is a good method to give information about coding, But it is difficult to write a good comment. In this article, I write about my tips for good comments.

Why some comment is useless?

Why some comments are useless? The answer is that they tell useless information.

I give some examples.

  1. comment out
// const flag = true

It is awful. Why this line is commented out? When Should I uncomment it?

  1. description
//"if the flag is on, Error will be thrown"

if (is_error_flag) {
    throw new Error("error");
}

This comment is really useless. This information will be found If you read the code.

What is a good comment?

I think a good comment helps us to understand the below thing.

  • Why our code is written this way.
  • When we should change our code.

Example is below.

// MEMO if you want to debug this function, please uncomment it. 
// const flag = true
// TODO should Add tests about below 
if (is_error_flag) {
    throw new Error("error");
}
// FIXME I couldn't come up with good naming. Please fix it. 
const temp2 = 34

Conclusion

I always point out same thing. So I summarized. I hope this article helps you.