While this is a nice article, I will mention that the line-by-line comments you see, even on i++, may be important - "i" may not just be a loop increment. If the increment operator is overloaded on object "i", then it might be a lot more than just an increment (perhaps the person that wrote "i"'s class was trying to be too clever). Never assume that just because the code *looks* obvious, it is. Perhaps the developer writing the comment knows something that you do not, and that should always be the (safe)presumption or assumption.
I partially agree (especially about advice to not comment
the 'what' and the version history).
Anyway, here's some food for thought:
1. The productive code base alone cannot serve as self-documenting code. But what about tests? Some people favor test-driven development (TDD). As Ron Jeffries said,
a test is a working example, whereas examples shown in a
comment may be totally out-of-sync with the codebase.
2. On some platforms, e.g. Python, you can embed examples
in documentation and have a tool run them automatically. This works because Python does not throw the comments away,
certain comments (the infamous "docstrings") are preserved
to be available at runtime.
2. Logging can be an alternative too, especially
if your project policy forces you to deliver
logging code anyway. Log lines are even better
than comments in that they show you (and other
developers) the flow of your logic at runtime (and