&gt; will love you for documenting the WHY just as much as s&#x2F;he&#x27;ll hate you for having to rely on documentation that explains the WHAT.<p>I&#x27;ve saved myself so many times with this.  External services are bad about having odd-ball edge-case errors that require a little funny business on your end in order to keep operational.  So there are often little code snippets that look like their bugs, but are actually necessary to prevent regressions.  Without a comment as to <i>why</i> the code is there, some boy scout is going to &quot;fix&quot; it (and the now failing unit test) and introduce a regression.