Imagine if you came across this in actual code. You might first check if the code was changed recently and by whom, and whether the comment or the code came first. But that still wouldn't tell the whole story. To get it all, you would find out who checked in the code, and what their original intent was.

What we're advocating is to treat source code more like a design document. It's a collection of thousands of design decisions all informing the specification of the final product, the program.

> If the idea is simply that this is extra work for the programmer to do -- that they need to describe every implementation twice, once in code and once in English

Right, so the point is that prose is not redundant. As Knuth put it literate programming is "a mixture of formal and informal methods that reinforce each other." When we communicate to one another face-to-face, we use gestures, expressions, intonation, etc. to articulate an idea. On the internet, when we communicate with just text, much of my meaning is lost forever and never apparent to anyone who reads this.

Programming is much the same way. The code only tells you so much about the program. Without any context, readers are often disoriented and confused by new codebases. If no one is willing to read your code, no one will ever contribute to it. GitHub and SourceForge are veritable graveyards of amazing yet abandoned projects that will never see another contribution, because their codebases are so inscrutable. I know I'm guilty of this as well; when I revisit old codebases, I hardly know even what I was thinking.

Anyway, I think there's a lot to explore here. I think what you raise is an issue, and it will always be important to address, but I really believe that literate programming is important and can lead to better code. So we're going to see where we can take it with Eve, and I hope you'll give it a shot!