It is tackled at the very end of the article, but there is a very good and a totally valid use of the comments: answering "why?" questions (as opposed as describing the code).<p>This propagates to all other advice in this article.<p>Magic numbers? Comments can be good be useful if they answer "why"<p><pre><code> PACKET_SIZE = 32 # Section 3.5.7 of RFC-99999
</code></pre>
TODOs? Comments can be good if they answer "why" (as in, "why haven't this been done yet)<p><pre><code> # TODO: once #1234 is fixed, rewrite as a binary search (right now it is not supported)
</code></pre>
After-update notes? If the action is optional, make it a comment -- this will make upgrading to latest version easier.<p><pre><code> # This function is present in libfoo-1.23, but our version is older, so we are re-implementing it here.</code></pre>
People who think comments are a code smell have generally never had to go back to a codebase they haven't touched in 3-6 months.<p>This cures all illusions.
Comment everything. The worst thing that can happen is somebody concludes "nope, that's not true anymore." To avoid describing the system entirely is nothing but laziness. Rationalize it however you like, it's just laziness.