C Y writes:
Well, it's more a case of convenience, but the psychology is good too - when you write a piece of code the text describing the purpose of the code is right there for reference/documentation, and if you need to update the spec due to code enhancements it's again right there. It's the whole "literate programming" thing. I know actions speak louder than words on such things though :-/.
I know only very little about literate programming, but it seems to me hard to obtain in an advanced programming language like CL, where the actual implementation of some functionality could be spread out over several files, so that you could not naturally get a textual association between the code and the spec. Also, there is obviously a lot of code that corresponds to nothing at all in the spec, but which should be documented nevertheless. It looks to me like an integrated documentation system like Concordia would be more appropriate. Luckily, McCLIM would be ideal for implementing such a system. Now, we just have to find someone to do that.