h a l f b a k e r y
Strap *this* to the back of your cat.
add, search, annotate, link, view, overview, recent, by name, random
news, help, about, links, report a problem
or get an account
Literate programming combines software
with its documentation (comments++) to
create a work of technical literature
which can be both read and compiled.
Articulate programming goes one step
further. The code is annotated with
natural-language explanation (at both
high and low levels, across
components, in a way suitable for the
current user's level of technical
expertise) so that it can actually
explain what it's doing to the
``Error loading Web page.''
(Note: lots of software stops here.)
``Host not reachable connecting to IP 184.108.40.206.''
(Note: even the best software stops here.)
Click: ``Why were you <connecting to IP 220.127.116.11>?''
``The user followed a link to host foo.com,
no proxy is configured, and the resolver
listed IP 18.104.22.168 for foo.com.''
Click: ``Why did you think <no proxy is configured>?''
``Could not read proxy configuration file /etc/foo,
using default behavior.''
Click: ``Why couldn't you <read proxy configuration file>?''
``open("/foo/bar",O_RDONLY) returned "Permission denied."''
This is obviously useful for
troubleshooting, but also helpful for
when software does something unexpected.
``Why did you just highlight that?''
It would also be a great educational
aid, teaching people what actually goes
on behind the scenes without overwhelming
The œ-bakery idea that inspired me to post this one. [egnor, Apr 28 2000, last modified Oct 05 2004]
How To Write Unmaintainable Code
The antithesis of this idea... [dgeiser13, Apr 28 2000, last modified Oct 05 2004]
||Most expert systems do behave in this manner. Using recent generation
tools like Prolog-III or OZ (constraint-based language)
one programs by specifying rules, rather than explicitly
specifying behavior. Because execution means applying
rules until a resulting correct behavior is found to execute,
one can work at a 'meta-level' and ask the system
what rules it applied to come to the conclusion it did.
In the last few years PCs have become powerful enough,
and logic and constraint-based languages
efficient enough, to use this technique in popular
applications. We just do not have enough programmers
trained in these techniques or we would see more
||whoa -- this is like a stack trace on drugs :) Implementing a system like this would force programmgers to explicitly define what each part of a program does in a sort of outline form, which has the additional side-effect of making programs much more readable, and source documentation much more comprehensive.
||"I still have no idea why the app crashed, but I think I'm finally ready to forgive my parents."
||I'm not sure the documentation would have to be that cumbersome, as part of coding any project (in an ideal world) you already have a design doc implemented that contains a flowchart mapping every possible function call and result. If there was a system for inputting and reading this flowchart, along with some natural language (NL) text strings, one could conceivably imaging the beginings of such a NL error response framework. Of course even your OS would have to return NL text formatted error messages, or you would have to compile a lookup table with common error numbers and associated NL strings.
I think this is a bloody brilliant idea, and can't believe I didn't come up with it myself, what with all the coding I do. Of course, I've prolly just habituated to accept "Segfault. [BLAH]" as a valid error message...
||"Error loading Web page.''
"Host not reachable connecting to IP 22.214.171.124.''
Click: "Why were you <connecting to IP 126.96.36.199>?''
"Error finding next message."
That Unmaintainable Code essay is brilliant. I have followed it wherever possible, and it has never led me astray. ;)
||This might give you problems in an environment where one program (written nicely in this new way) had to interact with a bunch of programs (or components, libraries, etc.) not written in this way.
||I can imagine finding that the explanation petered out just as it was about to get interesting, and then cursing a lot.
||I suppose that's similar to what [Detly] said.