This is an excellent article, making several points that I would not have thought of if I were to write on the same topic (point 11, for instance.) I would, ho

This is an excellent article, making several points that I would not have thought of if I were to write on the same topic (point 11, for instance.) I would, however, like to make a point about commenting, as there are at least three related cases where renaming identifiers and restructuring logic is not sufficient. The first thing is where one is doing something non-obvious on account of an unintuitive (and possibly undocumented) fact about either the problem domain or some remote part of the the system that it is infeasible to change; the second is some non-obvious corner-case (a subtle issue of thread- or exception-safety, for example); and the third is where the algorithm itself is non-obvious (Jon Bentley wrote of a colleage who found that one of his algorithms had beem 'fixed' and 'improved' to the point where it was no longer efficient; a suitable comment might have avoided that (and there's also the famous /* You are not expected to understand this */, for which no mere restructuring or renaming seems to offer an effective alternative.)) I am sure you are aware of these exceptions, but not everyone on the comment-deprecating bandwagon seem to do so. https://en.wikipedia.org/wiki/Lions%27_Commentary_on_UNIX_6th_Edition,_with_Source_Code#%22You_are_not_expected_to_understand_this%22 https://en.wikipedia.org/wiki/Lions%27_Commentary_on_UNIX_6t...