From: utzoo!decvax!watmath!djmdavies
Newsgroups: net.misc
Title: Re: Self-documenting code???? Sheesh!
Article-I.D.: watmath.2600
Posted: Sat Jun 12 15:37:39 1982
Received: Sun Jun 13 04:58:24 1982
References: ihuxl.166

I agree; code as such is rarely self-documenting to anyone other than the
author for the next three days (or thereabouts), and only if under one page.
In fact that applies even (usually) to code with imbedded comments of the
usual kinds--specific to the local statements.

What I find is most critically needed on any program source of more than a
page is a high-level overview of what the program is all about, and generally
how it is structured.  Especially documentation of any data structures
involved.  Someone, I forget who, said that if you really understand the
data structures in a program, then you understand the program. Though that
obviously cannot be true for applicative programming styles.

I'm not especially interested in listings of variables and where used, as such;
that sort of thing ca be got with automated tools when one really needs it.
		Julian Davies,  univ. Western Ont.