[comp.software-eng] Evolving Comment Styles

jerbil@cit-vax.Caltech.Edu (Stainless Steel Gerbil [Joe Beckenbach]) (02/22/89)

	As I was following the thread of discussion about comments and
'good coding style' with regards to these, I thought of a neat little shift
which I think embodies what this facet of software engineering should head
towards: not "self-documenting code" but "self-coding documents".

	The Hyper-Programming idea thrown out by one participant gives the 
right slant: combining the documentation, graphics, and code into a more
comprehensive source. I'm not saying that this type of environment is for
everyone [heck, it'll have trouble fitting onto most of the current computers,
which are smaller than the Vax I'm working on]; it's just that this concept
brings the commentary, the documentation, and the human-readable context of
the code in question [including design!] into a spotlight where the driving
expression behind the code can be given at several levels and in several
forms. I'm getting ready to go back and help work on some code I wrote last
summer; at the time I thought I was writing enough comments and documentation;
I'm pretty sure I'm going to have quite a surprise when I start trying to
correct my misunderstandings of my own code.

	Just my two cents and a new twist on an 'old' viewpoint.
-- 
Joe Beckenbach	joe@csvax.caltech.edu	Caltech 256-80, Pasadena CA 91125
Users I'd like to see:
	Postmaster@link.L5.edu		gorby@party.kremlin.gov.cccp

brooke@ingr.com (Brooke King) (02/25/89)

In article <9674@cit-vax.Caltech.Edu> jerbil@cit-vax.caltech.edu (Stainless Steel Gerbil [Joe Beckenbach]) writes:
| 
| 	As I was following the thread of discussion about comments and
| 'good coding style' with regards to these, I thought of a neat little shift
| which I think embodies what this facet of software engineering should head
| towards: not "self-documenting code" but "self-coding documents".
| 
| 	The Hyper-Programming idea thrown out by one participant gives the 
| right slant: combining the documentation, graphics, and code into a more
| comprehensive source.

| 	Just my two cents and a new twist on an 'old' viewpoint.

Some old information which is somewhat related:

Iris Vessey and Ron Weber, "Stuctured Tools and Conditional
Logic:  An Empirical Investigation," _Communications of the ACM_,
January 1986, Vol 29, Nr. 1, pp. 48-57.

The article empirically hints at what we all feel, that linear
programming languages are inferior to well-done multi-dimensional
(perhaps graphical) programming languages.

The whole August 1985 issue (on visual programming) of _IEEE
Computer_ is pretty interesting and some of it was referenced in
Vessey and Weber.

Anyone have any pointers to some more recent work (that is also
not too heavy)?

| Joe Beckenbach	joe@csvax.caltech.edu	Caltech 256-80, Pasadena CA 91125
| Users I'd like to see:
| 	Postmaster@link.L5.edu		gorby@party.kremlin.gov.cccp
-- 

brooke@ingr.com uunet!ingr!brooke W+1 205 7727796 H+1 205 8950824