From: Dido Sevilla Date: 2004-10-13T07:30:05+09:00 Subject: Re: documentation as source On Tue, 12 Oct 2004 11:59:02 +0900, Randy W. Sims wrote: > Are there any Ruby modules that allow documentation to act as source > code? I was thinking of the problem of how souce code sometimes diverge > from its documentation. So maybe there could be a way to specify the > interface: the number of arguments and their types in the documentation, > and possibly pre- and post-conditions, and then the documentation would > be turned into code at runtime. I guess this would be implemented > something like Perl's source filters[1]. Possibly some constants and > such could be defined this way as well, version numbers, etc. > > I'm not sure if this is a good idea or not; I haven't completely thought > it through. It seems like I've read about this being done before in some > other langage, but a brief search hasn't turned up anything. As other people have mentioned, what you're talking about is essentially literate programming. It's an idea that originated with the great Donald Knuth himself, and actually doing it actually represents a major shift in the philosophy you have while programming. The primary task of programming changes from explaining to the computer what you want to do, to explaining to *people* what you want the *computer* to do. I've been doing this kind of work using Norman Ramsey's Noweb literate programming tool (http://www.eecs.harvard.edu/~nr/noweb/) and what I can say after doing it for a while is it can be quite difficult. It forces you to be more careful about design, as you're supposed to be able to explain why you're doing everything, but it is a lot of work. It does pay off in the end: look at TeX. It's one of the few nontrivial programs that can actually make the claim of being Bug Free(tm), without it being an overly egregious lie.