The Design of Software is a Thing Apart
&gt; Those who speak of “self-documenting code” are missing something big: the purpose of documentation is not just to describe how the system works today, but also how it will work in the future and across many versions. And so it’s equally important what’s not documented.<p>Documentation also (can) tell you <i>why</i> the code is a certain way.  The code itself can only answer &quot;what&quot; and &quot;how&quot; questions.<p>The simplest case to show this is a function with two possible implementations, one simple but buggy in a subtle way and one more complicated but correct.  If you don&#x27;t explain in documentation (e.g. comments) why you went the more complicated route, someone might come along and &quot;simplify&quot; things to incorrectness, and the <i>best</i> case is they&#x27;ll rediscover what you already knew in the first place, and fix their own mistake, wasting time in the process.<p>Some might claim unit tests will solve this, but I don&#x27;t think that&#x27;s true.  All they can tell you is that something is wrong, they can&#x27;t impart a solid understanding of <i>why</i> it is wrong.  They&#x27;re just a fail-safe.