How can comments be a security issue?
- If you have to use comments to explain your code, the code is probably too complicated. When creating a complicated solution to solve a problem you insert errors, bugs or just making it har to maintain.
- A comment that doesn´t describe the code correctly may lead readers of the code to think it does something it doesn´t, making it harder to maintain.
- Comments gets stale, when you change/refactor your code you´ll forget to change your comments. Se #2.
- It may be hard to correctly describe what the code does in plain text. Se #2.
Code should be written in a way to make comments redundant.
For example give methods, variables and fields names to describe what they do or what they are representing is a good start.
Use comments to document how to use classes and methods, for other programmers using them to know how to. Be sure to update the documentation as you change/refactor the code.
Finally a quote I really like:
"When I have a specific goal in mind and a complicated piece of code to write, I spend my time making it happen rather than telling myself stories about it." - Steve Yegge