He has also written an article on how he writes the code comments [0]; I've been using Design, Why, and Teacher comments a lot in my last projects and they have been very helpful, especially if you come back to the project after a long time or introduce a coworker to the code base.

[0] http://antirez.com/news/124

I try to comment my code in a similar way, often ending up with up to 30% comment to code ratio. I know some (many?) people are very dismissive of this style and reject the idea you have to write any comments where the code is ‘self explanatory’, but I don’t care. It doesn’t take me a lot of extra time to document the general idea behind a piece of code and it makes my future life and that of other devs reading the code so much easier it’s easily worth the effort to write these comments and keep them up to date.

Like I said it’s rare to see OSS code written that way though, I’ve even thought on multiple occasions that some projects actively strip all code comments automatically for whatever reason, considering the total absence of any form of code documentation in them.

I'm one of those, but in your defense I think we need to maintain a very high bar for "self explanatory".

At the same time, I think it's important to be aware that comments not immediately adjacent to what they describe are usually not visible in code review, are often not visible to the person editing the code in question, will fall out of date without an active process to keep them up to date, and at that point will do more harm than good.

I'm curious if you have any particular mechanisms for addressing the above?

I'm trying in my current setting by introducing a mechanism for cross-references (anywhere in the repo, ^^{label} refers to @@{label}) that my CI setup can recognize and surface during code review. It's provided a bit of benefit, but it's underused, and it's too soon to have a good sense of long term impact.

I put 'self explanatory' in square quotes exactly because of that, at the time of writing the code many things may seem self explanatory for the person writing it, but even seemingly simple things can be very confusing for people who read the code for the first time. But obviously I'm not advocating comments that simply describe in words what the next line of code does mechanically, those are useless. But I do like comments that break up the algorithm in sections that are clearly marked by comments, even if some parts of those comments may seem trivial ('loop over all objects of type x and process those with property y', etc). For me the value is in being able to read the comments first and get an idea of the structure of the code and the though process behind it, before actually having to interpret the code itself.

>> At the same time, I think it's important to be aware that comments not immediately adjacent to what they describe are usually not visible in code review [..] I'm curious if you have any particular mechanisms for addressing the above?

Not really. In our team we don't really use code review tools for feedback about algorithms or higher level design of the code, my experience they are pretty awful for that anyway. We use bitbucket primarily to point out local improvements and ask questions why sections where added or changed, but for higher-level discussion we prefer offline tools like whiteboarding, and rotating people so everyone works on different parts of the codebase.

The main challenge I have is not all engineers are equally willing/comfortable/able to communicate their ideas in this way. Sometimes because of ingrained preference (comments are never necessary), other times because of language barriers.

https://github.com/flashcode

WeeChat is written in a very clear and easy-to-follow C.

I love Michael Fogleman for graphics: https://github.com/fogleman/Craft