22 Mar
2018
22 Mar
'18
5:48 p.m.
arnold(a)skeeve.com writes:
Doug McIlroy <doug(a)cs.dartmouth.edu> wrote:
In mid-1985 I independently had the idea that combining code and
documentation would make it easier to keep them in sync. I wrote
a program called "xman" for "eXtract MAN pages" that generated troff
man pages from special comments that began with /**. A few months
later I got a course proposal accepted by SIGGRAPH and asked James
Gosling to participate. During one of our get-togethers I showed
him xman. While correlation doesn't equal causation (and James
doesn't remember), /** reappeared in JavaDoc which spread like the
plague to doxygen et. al.
We abandoned xman after a few months. It was an interesting experiment,
but was only "useful" for producing large volumes of nicely typeset
utterly irrelevant documentation. Which, of course, since many others
have since drunk the Kool-Aid, is the state of much documentation today.
What works for me documentation wise-is:
o Block comments that say what the code does, not how it does it unless
it's not obvious from looking at the code.
o Inline or block comments for things that aren't obvious.
o Separate BTL-style document that explains what the program does,
describes the data structures, and how the different parts of the
program manipulate those structures. Sometimes that can go in a
code file if it's a small and simple program.
While I'm at it, my two cents on the NULL topic. I use '\0' for NUL
as that's not the same as NULL. When I want NULL, I always cast it,
for example, (struct foo *)0 because that locally provides some often
non-local information about the type of the things that's being compared
or set to NULL.
Jon
Knuth offered the remedy of "literate
programming", which
might help in academic circles. In business, probably not.
IMHO this is too bad. Code I've written using LP is generally
more correct earlier on than otherwise. And it's very enjoyable
to write code and explanation at the same time; I feel like I'm
talking out loud directly to my reader, a person, and not just
coding for myself or the compiler.
Significant proofs by example are Knuth's TeX and MetaFont,
and the lcc compiler by Dave Hanson and <I forgot>.
Shameless plug: I have written a small LP system in gawk designed
for use with the Texinfo markup language. It is written using itself.
I have written two other good size awk scripts using it as well.
I think it will scale well to larger stuff in C or C++ but simply
have not had an opportunity to use it for anything like that yet.
See https://github.com/arnoldrobbins/texiwebjr if interested;
and feel free to follow up privately instead of on the list to keep
things on topic.
Thanks,
Arnold