[jeffdavis]

Unfortunately the explanations aren't left as code comments, so they may be lost.

One ting nice about code review is that the code must stand on its own to pass. That means that it's likely to be understandable a year from now.

[w_t_payne]

Written documentation does have the advantage of being persistent, and supports an unlimited producer-to-consumer fan-out. However, documents have a pretty lousy bandwidth and knowledge retention rate compared to face-to-face communication. If you are working in a small team with low staff turnover, face-to-face beats written docs hands-down as a knowledge transfer mechanism. On the other hand, if your staff turnover is high, or if your team is huge, then you absolutely need to write everything down. I am working in a small team, with low turnover, so face-to-face works best for us in this particular instance. (We still document what we do pretty well, though, with both regular source commentary and tools like Doxygen, but as a matter of professional pride rather than necessity).