Literate programs sound fascinating. Is there somewhere I can read more?
I've always thought self-documenting code was the way to go.
I've always thought self-documenting code was the way to go.
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.
See http://axiom-developer.org/axiom-website/litprog.html for an example of a trivial literate HTML program.
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.