Literate programming is many things, some of which very
useful for certain tasks, rather than a dogmatic figment of
development process:
- a way to add rich comments into living code
- an illustrative way to include code into article text
- a better alternative to attaching code in a separate file
- a process of weaving and tangling (doc markup and code)
- single-click delivery of well-documented code written in
and residing on the web from a single source
The Literate Tool is part of J Wiki
http://www.jsoftware.com/jwiki/Literate
Now there are 37 separate Wiki articles in J Wiki, written in
Literate style. None of which is dictated by Literate imperative,
but rather Literate format was called upon as a lucky convenience.
Most compelling: there is no other known system to date which
allows combining rich markup and illustrative graphics with
code, so that you don't have to keep it in a separate document.
To address some of the "myths" about literate programming:
- debugging: resulting code is regular source, which of course
can be debugged
- effort to write the doc text: Literate does not dictate how
much text is needed, so it could be zero text; it works the
other way around: when you need (a rich way) to express comments,
Literate offers a nice medium. If you don't NEED narration or
rich text--don't use Literate. But then it is telling about
the challenge and complexity of such programming.
- text interfering with code (finding code): in resulting document,
as in Wiki, the separate is very visible. Good balance and organization
makes sure that the document narration is well balanced with code
structure. Complex algorithms with graphical illustrations will
benefit from more text and less code ratio; other programs can have
text well separated from uninterrupted passes of code. It could be
just a short intro and heading comments above groups of functions.
- clean code is better: Literate does not replace good coding
practices, it merely complements them, especially when appropriate.
So if you don't need Literate, don't spend your breath criticizing it,
if you do, see the J Wiki and start using it.
----------------------------------------------------------------------
For information about J forums see http://www.jsoftware.com/forums.htm
