20 Nov
2011
20 Nov
'11
7:45 p.m.
I've read up on literate programming (I even own a
copy of "Literate
Programming" by Knuth) but even so, I never liked the idea all that
much, because it seems even *more* work than regular programming.
Sure. Writing better code _is_ more work.
[...two anecdotes...]
Never time to do it right but always time to do it over? I can
sympathize; I've been there myself. Too often.
-spc (And frankly, after seeing some of the
"documentation" we
produced at work [6], literate programming would still be a
failure)
"Make it possible for programmers to write in English and you will find
programmers cannot write in English." (Not that the phenomenon is
restricted to English, of course.)
In general, ability at skill A correlates negatively with ability at
skill B, unless the skills are closely related.
This does not mean that code isn't better when propertly documented.
It just means that some - perhaps even most - people can't write good
documented code. Since you're looking at people selected for the
ability to write code, you see it as a failure writing documentation;
look at people working as tech writers and you'll see it as an
inability to program.
Sturgeon's Law applies. Expecting all programmers to be able to
produce good literate code is like expecting all programmers to be able
to write good Lisp, or expecting all cooks to be able to cook anything,
or all drivers to be able to drive an 18-wheeler competently, or etc.
/~\ The ASCII Mouse
\ / Ribbon Campaign
X Against HTML mouse at rodents-montreal.org
/ \ Email! 7D C8 61 52 5D E7 2D 39 4E F1 31 3E E8 B3 27 4B