From: ebergman@isis.cs.du.edu (Eric Bergman-Terrell)
Subject: Re: Please.  (Was Re: I Hope the BC++ IDE Editor Supports OLE Soon)
X-Disclaimer: Nyx is a public access Unix system run by the University
	of Denver for the Denver community.  The University has neither
	control over nor responsibility for the opinions of users.
Organization: Nyx, Public Access Unix at U. of Denver Math/CS dept.
Distribution: usa
Date: Sun, 12 Apr 92 20:09:26 GMT

In article <1992Apr12.184918.618@mnemosyne.cs.du.edu> junrue@isis.cs.du.edu (Jack D. Unrue) writes:
>In article <1992Apr12.020942.13848@mnemosyne.cs.du.edu> ebergman@isis.cs.du.edu (Eric Bergman-Terrell) writes:
>>In article <kuede7INN40h@alhena.usc.edu> ajayshah@alhena.usc.edu (Ajay Shah) writes:
>>>I sure hope I don't encounter your source code someday when I'm alone
>>>in a dark ftp site.
>>
>>What are you afraid of?  You might find diagrams of my data structures.
>>Wouldn't that simplify understanding the code?
>>
>[a whole bunch deleted]
>>
>>Using something like OLE, the comment block would be represented by a small
>>icon, that when selected would display the text.  Inexperienced readers of
>>the code would probably want to select the icon, read the text once, and go
>>on.  Experienced readers would already know about the function, and would
>>not need to examine the code.  Hence the code would be less cluttered with
>>comments that aren't always interesting.
>>>If you do so, please have an option to strip the gunk on demand.
>>
>[more deleted]
>>Well the "gunk" is implicitly stripped.  You only get it if you ask for it
>>by selecting the icon.
>>
>
>I believe the point that Ajay was trying to make (and if you weren't, Ajay,
>I'll make it anyway) is that all that "gunk" represents a lot of overhead.
>These illustrations are presumably stored along with the source code you would
>be annotating, right?

Interesting question.  I'm not sure where OLE objects are stored, but probably
in the "host" file.

>
>How much longer will it take to download such annotated source?  How much more
>disk space will it consume? (Consider that some people are irritated with the
>fact that the popular compilers today occupy on the order of 8-10 MB, imagine
>if all the supplied example source and other bits of code had your type of
>annotation).
>
>You can compress that stuff, but then the source itself is that much less
>accessible.
>
>You absolutely do want to make your code understandable by others, but my
>philosophy is that properly written comments and proper programming style
>should in itself handle most of the job.  If you want to expand upon an

Agreed.  But I'm tired of writing comments like this:

/*
If object is an atom, then return an equivalent object.

It IS necessary to return a pointer to a copy of the atom (with a nil cdr)
rather than a pointer to the orignal atom.

Reason:  Consider the representation of the function call (fun 1 2):

 car cdr
---------    ---------    ---------
|fun|  -|--->| 1 |  -|--->| 2 |  -|---|||
---------    ---------    ---------

If during the function call pointers to the original actual parameters
are pushed, the formal parameter corresponding to 1 will have a cdr pointing
to the second actual parameter.  Thus pointers to copies of the actual
parameters with nil cdrs must be pushed.
*/

>algorithm, draw diagrams to help explain, or whatever, make that a separate
>document.  Then all the "gunk" will be implicitly stripped out.
>
>How about making the illustrations, etc., in a separate file but provide hooks
>such that if the file is present, then the hypermedia links work, but if it
>isn't, then they don't?

Sounds like a great idea.  

>--
>Jack D. Unrue
>junrue@nyx.cs.du.edu

Terrell