Buy a copy of Physically Based Rendering (Pharr and Humphreys). It is a literate program that won an academy award. Make that your "gold standard" for good programming.
Literate programs explain "why", not "what". Think of a literate program like a physics textbook. Your code is the equations but your explanations (not comments!) give the reader the reason WHY you wrote the code.
Literate programming is a method introduced by Donald Knuth (http://en.wikipedia.org/wiki/Literate_programming). I've stumbled upon it whilst reading Physically Based Rendering, and then LCC: Retargetable C Compiler.
There are some programs that can turn the "documentation" into code : http://en.wikipedia.org/wiki/WEB , but most of them are quite old AFAIK.
I've always thought self-documenting code was the way to go.