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.
Date: Sun, 12 Apr 92 02:09:42 GMT

In article <kuede7INN40h@alhena.usc.edu> ajayshah@alhena.usc.edu (Ajay Shah) writes:
>ebergman@isis.cs.du.edu (Eric Bergman-Terrell) writes:
>
>>I'm excited about the potential for using OLE in a compiler's text editor.
>>In addition to leaving voice annotations, etc., documentation could be inserted
>>in-line.  The documentation could be diagrams, word processor text, voice 
>>samples, even animated video.
>
>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?

>
>>Perhaps one of the reasons we programmers are often reluctant to write
>>in-line documentation is that the tools (tty-style editors) are so primitive.
>
>A tool like Emacs can hardly be called primitive, and the fundamental
>barrier for 90% of people is that they have not invested enough time
>and thought about programming.  Just like fancy debuggers don't turn a

Emacs is not primitive.  Its output, unlayered linear ASCII text, is.

>bad programmer into a good one, animated commercials inside source
>code won't either.

And MIDI software doesn't make good composers either.  So what's your point?
The pros will always take advantage of the best tools.

>
>Programming is intrinsically hard.  What you are talking about is YA
>distraction which detracts from the basic focus which a good programmer
>should be obsessed about; i.e., his algorithms, his data structures,
>his code quality.

Hmm.  Is the understandability of the code part of your equation?  I know that
other programmers would probably benefit from pictures inserted in some of
my software describing the data structures and algorithms.  Look in some
of your programming books.  Watch other people describe data structures and
algorithms.  They often use pictures. 

>
>A good applications package may yearn for it's users spending 
>many an afternoon hitting buttons, but as a programmer I avoid
>such "user friendly" toys.
>
>User friendly -- you spend 15 minutes learning how to use it, and
>the rest of your life struggling to get your job done.
>
>>I'd really like to insert a drawing to describe the interesting data structures
>>in my programs.  Animation might be overkill, but imagine how it would help
>>someone else understand the code!
>Have you read Rob Pike on "excessive comments"?
>

You're making my point for me.  Comments can easily get excessive in a flat 
ASCII file.  Consider the following:

void turbo_qsort(...)

/*
line after line of comments about function behavior, arguments, etc.
line after line of comments about function behavior, arguments, etc.
line after line of comments about function behavior, arguments, etc.
line after line of comments about function behavior, arguments, etc.
line after line of comments about function behavior, arguments, etc.
line after line of comments about function behavior, arguments, etc.
line after line of comments about function behavior, arguments, etc.
*/

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.

void turbo_qsort(...)

+-----+
|Info |
+-----+

An even better technique might to encode items with further documentation
with a special color.  Selecting such specially colored items would make
their comments visible, but by default the source code would not be cluttered
with comments.

>>IN SUMMARY:  Compiler vendors (Borland, Microsoft, etc):  Please support OLE
>>in future releases of your compilers' text editors.  No need to do anything
>>terribly fancy - just allow users to embed objects and don't compile them!
>If you do so, please have an option to strip the gunk on demand.

Well the "gunk" is implicitly stripped.  You only get it if you ask for it
by selecting the icon.

>
>"Thrilled writing C with Emacs"
>
>        -ans.
>-- 
>
>Ajay Shah, (213)749-8133, ajayshah@usc.edu

Your posting left me confused.  Are you opposed to GUIs in general, or just
to applying GUI techniques to improve the programming craft?

A fascinating project (and I'm sure, not a terribly original one, these
days) would be to research how hypertext techniques would improve the 
programming craft.

A good start would be to read Ted Nelson's "Dream Machines", MS Press,
ISBN 0-914845-49-7.  Nelson makes the point that linear text is an artificat
of printing technology.  Computers allow non-linear text, which often results
in greater efficiency of reading, etc.

Some of these concepts are already in place (for example, on-line help in
MS Windows, BC++ IDE, etc).

In summary, you're right about the programming craft being hard.  It's hard
to write good software.  It's hard to describe good software.  It's also hard
to learn software someone else has written.  I think we should use technology
to make some of this easier, so that software can get better.  Surely there's
a better way to represent programs than as a set of flat ASCII files.

Terrell