in reply to Re^5: An Introduction to Literate Programming with perlWEB
in thread An Introduction to Literate Programming with perlWEB
Will the actual state of the code drift from the internals documentation? Yes, certainly, but that doesn't make the docs useless-- at the very least they tell you something about where the codebase was at an earlier stage. When you're getting used to an unfamiliar code base, any hints at all are worthwhile.
And I would suggest that what the perlguts example really illustrates is that the distinction between internal and external is fuzzy, because that boundary moves around depending on what you're doing -- to an XS programmer, perlguts is the API, to me, it documents some internals I don't need to think about just now.
Note that if you put every routine into it's own module with it's own API to document, then there would be little difference between your position and mine.
There's nothing "religious", no "neat, idealized doctrines" involved. Just simple, practical, proven methodology derived from hard won experience.That's what they all say.
Not my ideas, nor my experience, but that of 50 years of those that went before us.You mean the experience of guys like Donald Knuth?
|
---|
Replies are listed 'Best First'. | |
---|---|
Re^7: An Introduction to Literate Programming with perlWEB
by BrowserUk (Patriarch) on Jan 22, 2009 at 12:12 UTC |