Commenting is inherently dangerous.
- Use it sparingly for
// fixmes
Why dangerous?
- Code comes and go, but comments are always left behind.
- People fear deleting comments, because they assume it to be vital true information.
- Try understanding code with vital FALSE information.
I consider bad commenting, one of the deepest layers in Programming hell.
A function name [for example] however, is less likely to become inaccurate as you change things within it, and if its functionality does change, you are naturally more likely to change the name of it as well.
This is one fundamental but important reason why a long name is preferable over commenting, and why it will lead to cleaner code.