[paulannesley]

> That last part is ultimately the most important lesson from this: Comments matter!

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 https://twitter.com/nzkoz/status/538892801941848064 ) and create a lot of noise that make reading the code harder (especially when the comment and code contradict each other).

I only leave brief comments where some code is necessary but at a glance doesn't look right, or has a non-obvious reason. But first I find a way to make it look right or be obvious.

[MichaelGG]

Comments are helpful as an overview of a module, briefly outlining what the goals and major ideas. I'm currently starting to work on a large project, all in C, heavily manually threaded, with essentially zero comments. It's open source so I can't complain, but boy does it make figuring things out difficult. Especially in C, where so much code is pushing bytes and pointers around, that there could easily be unintended functionality that might not be desired.

Getting devs to write separate documentation is more difficult than comments, and is more likely to get out of sync. Better if they write some general overview inline. (On the opposite end, I also recently reviewed a project that has almost no comments, except on calls to malloc and free, with comments "get some memory" and "release memory".)

[cperciva]

Comments can easily get out of sync with reality

This may be true, but I find that every other form of documentation becomes out of sync with reality even more easily, and/or is not in the right place to be noticed when some code is being edited.