Minimalism: Practical Guide to Writing Less Code (2002) [pdf]
> Prefer code to commentsI used to make this same argument, and then took it overboard by never commenting. After reading some literate codebases, I’ve changed my mind.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.I now follow a rule: a meaningful comment at the top of each file. A comment on every exported function / 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.