Literate programming is too much work! - Re: TeX - Knuth - Software quality - Re: Bug-Free Software,

I used to think that way, a decade or two ago. Now, I would say that's too large an audience not to. I'd say _one_ person is too large an audience to not document for. I have, repeatedly, written code and not documented it because nobody but me would ever mess with it. In most cases I've been right - but in plenty of those cases I have had to pick it up again a month, six months, a year later, and either spend longer figuring out the code than it would have taken to write documentation first time around, or throw the code out and rewrite it because that's the quickest way, then, to have code I understand. There's even one case I recall where I wrote a program, after some use discovered it had a bug, fixed it, picked it up a year or two later, puzzled over the fix, decided (incorrectly) that it was pointless, ripped it out, and then had to re-find the same bug and resurrect the fix - all because I hadn't documented any of what I'd done. (Fortunately the second time around I ran into the bug soon enough that ripping out the code was fresh in my memory.) Code without documentation is crappy code, I don't care how excellently it does its job or how clever it is or how otherwise clean it is. It doesn't have to be "literate programming" documentation; that's just a particularly good way of keeping code and documentation together and thus helping cut down on their drifting out of sync with one another. But it needs to be documented. And, before you ask, yes, I have written far too much code that's crappy in this respect. It is largely through observing the consequences of doing so that I have been forced to the above stance. This is not to say you have to document as you go, especially with experimental code. But if you don't document before the bits start rotting in your wetware memory, you will suffer next time someone - even if that someone is you - picks up the code. And wetware bitrot sets in quicker than you might think. My memory, especially for code, is far better than what I observe in most other people, and I would trust my memory for such things for a week or so, at most, unless I'm still actively working in the code in question. Don't worry if your programmers "can't write English". As much as I hate botched English, I will take botched-English documentation over no documentation any day - the only exception is if the English is so horrible that it's actually convenying incorrect impressions. /~\ 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