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.
- comment out
// const flag = true
It is awful. Why this line is commented out? When Should I uncomment it?
- 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.