Don't use comments, use code

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 &quot;why?&quot; 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 &quot;why&quot;<p><pre><code> PACKET_SIZE = 32 # Section 3.5.7 of RFC-99999 </code></pre> TODOs? Comments can be good if they answer &quot;why&quot; (as in, &quot;why haven&#x27;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&#x27;t touched in 3-6 months.<p>This cures all illusions.

Comment everything. The worst thing that can happen is somebody concludes &quot;nope, that&#x27;s not true anymore.&quot; To avoid describing the system entirely is nothing but laziness. Rationalize it however you like, it&#x27;s just laziness.