I know it’s almost heresy to say it, but comments in code are harmful.
We could start with Jesse Liberty’s post which suggests that you probably don’t need them. If you have a function that does something, use the function name to describe what it does, which is sound advice.
The problem with comments is that you end up with 2 models. One which says what is being done by the code, the other which says what is being done descriptively. But developers can already take code and work out what it does and form a descriptive version of that code in their minds.
OK, the argument goes that if you do it descriptively, you shortcut the process. But if you’re doing it descriptively, you still need to describe it in as much granular detail as the code, or else the documentation is incomplete, and will still require the developer to go and actually look at the code. So, comments are again pointless.
So, comments are pointless. But comments are, then, by their presence, harmful. You have two definitions of the logic. One written in a language the machine can understand, one in a language humans can read. What’s the chances that they are consistent? The only way to do so is to make sure that they are reviewed, in which case you have to hope that the developers care enough to review it carefully and that the management will fund it. In the world of Theoretical Methodologies this may be true, but down here on planet earth it rarely is.
And once you lose confidence in the comments, they are simply more code for people to scroll through.