The best-commented code I have ever seen is Doug Lea's malloc, or dlmalloc [oswego.edu], the malloc used in glibc, among other places. I had no idea how a malloc would work, and I wanted to write one for my OS class, so we looked at the dlmalloc source code. MAN, that's some well-commented code! Not only does it explain what individual functions do, but it also explains each general part of the algorithm in excellent detail. And it's malloc; it better not have any bugs!