20 Nov
2011
20 Nov
'11
11:21 p.m.
It was thus said that the Great Mouse once stated:
Have you tried writing a novel? Even writing 50,000 fictional words is
tough (ba dum dum!).
-spc (Also,
the intended audience for our work is ourselves (right
now, five programmers total) and we don't license or give out
the code. Too small an audience to write a series of novels,
frankly ... )
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.)
About the only time I've had that problem is when I modified sendmail.cf.
Otherwise, I don't really recall a time when I've gone back to code I wrote
years later and had trouble following it. Heck, I'm looking at some code I
stopped working on in 1999 and I'm not having any problems with it.
Amusement at what's there (hmm ... I must have started working on some
persitent objects ... interesting) yes, amusement at how my coding style has
changed since then, yes. Difficulty reading my own code? Not really (heck,
just last year I was able to improve the speed of a 6,000 line program (is
that all that is? Wow!) I last worked on in 1995, and the only
documentation *is* the code).
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.
And there are those that ignore comments in the code as they might not
bear any relationship to the code what-so-ever. I try to maintain comments,
but even so, there are times when the comments drift out of sequence with
the code (heh---I just modified some comments in another personal project
that referenced code that's been removed for six years!)
-spc (So, how many literate programs have you written? 8-P