Comments are invisible until the moment you need them.
When you understand your code, you don't bother to read the comments. As soon as you forget how the code works, you look to the comments for direction.
But if you didn't revise your comments along with your code, the comments will trick and deceive you until you realize that they're out of date. So you must re-grok the code anyway.
Use comments to describe your code's purpose. Let your code self-document the implementation.If you are particularly clever in your implementation, add a quick comment to explain your cleverness. When you realize you shouldn't have been so clever, be sure to remove the implementation comment as well.
This is why api-level documentation is great: functions are used for a purpose, and they're supposed to be a black box. If you keep your functions small and focused, you can just describe what they do, and it all works out.
When you understand your code, you don't bother to read the comments. As soon as you forget how the code works, you look to the comments for direction.
But if you didn't revise your comments along with your code, the comments will trick and deceive you until you realize that they're out of date. So you must re-grok the code anyway.
Use comments to describe your code's purpose. Let your code self-document the implementation.If you are particularly clever in your implementation, add a quick comment to explain your cleverness. When you realize you shouldn't have been so clever, be sure to remove the implementation comment as well.