The problem has to do with maintaining large, complex, and frequently changing projects. If your code tells me what the program is doing the first thing I have to do when debugging is ignore the comments.
If the comments describe the code this means I have to ignore all comments including those which may be relevant to my debugging. This causes a few specific problems in a collaborative environment.
The first is that the comments get stale/out-of-date/etc, more quickly and are therefore consigned to the archaeology of the program rather than of current relevance. At least with spurious logging, I can take it as a sign that someone had trouble with the code here. With comments I cant even tell if it was done in pseudocode and then translated below. It is useless.
The second is that you can't just add relevant comments into the mess without deleting all the other comments first. Otherwise they can't be sorted out easily or efficiently. In other words, it is worse than useless because it keeps proper, useful comments from being seen or read.
Third, if there are relevant comments there, such as
# This is the maximum value the standard allows for.
Then I won't see these and I am more likely to miss them and hence screw something up by accident.
A better approach is to recognize two things:
1) The code itself needs to be so clear, that you never need any comments for debugging (interface documentation is something very different), and
2) The code plus the documentation together has to be easily readable to the programmer. It also needs to be clear, concise, and avoid duplicating messages any more than needed. Duplication with the documentation of course is required by definition.
I hear a lot of people say they have code they would like to release open source but don't want anyone to see how horrible the code is. The answer is to learn to write code with a dual audience --- human and computer --- in mind. The code comments then function like footnotes would in a text, or as a way for two or three programmers to discuss/debate differences in approach. However, they are not debugging aids.
If the comments describe the code this means I have to ignore all comments including those which may be relevant to my debugging. This causes a few specific problems in a collaborative environment.
The first is that the comments get stale/out-of-date/etc, more quickly and are therefore consigned to the archaeology of the program rather than of current relevance. At least with spurious logging, I can take it as a sign that someone had trouble with the code here. With comments I cant even tell if it was done in pseudocode and then translated below. It is useless.
The second is that you can't just add relevant comments into the mess without deleting all the other comments first. Otherwise they can't be sorted out easily or efficiently. In other words, it is worse than useless because it keeps proper, useful comments from being seen or read.
Third, if there are relevant comments there, such as
# This is the maximum value the standard allows for.
Then I won't see these and I am more likely to miss them and hence screw something up by accident.
A better approach is to recognize two things:
1) The code itself needs to be so clear, that you never need any comments for debugging (interface documentation is something very different), and
2) The code plus the documentation together has to be easily readable to the programmer. It also needs to be clear, concise, and avoid duplicating messages any more than needed. Duplication with the documentation of course is required by definition.
I hear a lot of people say they have code they would like to release open source but don't want anyone to see how horrible the code is. The answer is to learn to write code with a dual audience --- human and computer --- in mind. The code comments then function like footnotes would in a text, or as a way for two or three programmers to discuss/debate differences in approach. However, they are not debugging aids.