Minimalism: Practical Guide to Writing Less Code (2002) [pdf]
&gt; Prefer code to comments<p>I used to make this same argument, and then took it overboard by never commenting. After reading some literate codebases, I’ve changed my mind.<p>Code is (almost?) always obvious to you as you are writing it. So, you never recognize code that is in need of a comment until you come back to it and struggle to understand its purpose and the context that gave it birth.<p>I now follow a rule: a meaningful comment at the top of each file. A comment on every exported function &#x2F; value. Often, in the process of writing the comment, I realize I’ve poorly named something or that I’ve failed to handle some case. Comments help guide the reader, but also the writer.