- unfortunately, many comments are not particularly helpful. the most common reason is that the comments repeat the code and to solve this problem it’s better after you write a comment the following question: could someone who has never seen the code write the comment just by looking at the code next to the comment? if the answer is yes then this comment does not make the code any easier to understand.
- another common mistake is to use the same words in the comment that appears in the name of the entity being documented.
- A first step towards writing good comments is to use different words in the comment from those in the name of the entity being described. Pick words for the comment that provide additional information about the meaning of the entity rather than just repeating its name