&gt; That last part is ultimately the most important lesson from this: Comments matter!<p>In most cases, logically granular commits with good commit messages, and a knowledge of `git log` and `git blame` etc, is better than leaving comments. Comments can easily get out of sync with reality (see <a href="https:&#x2F;&#x2F;twitter.com&#x2F;nzkoz&#x2F;status&#x2F;538892801941848064" rel="nofollow">https:&#x2F;&#x2F;twitter.com&#x2F;nzkoz&#x2F;status&#x2F;538892801941848064</a> ) and create a lot of noise that make reading the code harder (especially when the comment and code contradict each other).<p>I only leave brief comments where some code is necessary but at a glance doesn&#x27;t look right, or has a non-obvious reason. But first I find a way to make it look right or be obvious.