Newsgroups: comp.lang.apl
Path: watmath!watserv1!utgpu!news-server.csri.toronto.edu!rpi!zaphod.mps.ohio-state.edu!sdd.hp.com!elroy.jpl.nasa.gov!jato!kalessin!sam
From: sam@kalessin.jpl.nasa.gov (Sam Sirlin)
Subject: Re: J comment styles
Message-ID: <1991Apr29.181700.12298@jato.jpl.nasa.gov>
Sender: news@jato.jpl.nasa.gov
Nntp-Posting-Host: kalessin.jpl.nasa.gov
Reply-To: sam@kalessin.jpl.nasa.gov (Sam Sirlin)
Organization: Jet Propulsion Laboratory, Pasadena, CA
References: <1991Apr24.183906.14541@jato.jpl.nasa.gov> <24APR91.20363659@uc780.umd.edu> <ROCKWELL.91Apr25191520@socrates.socrates.umd.edu>
Date: Mon, 29 Apr 91 18:17:00 GMT

In article <ROCKWELL.91Apr25191520@socrates.socrates.umd.edu> you write:
|> I think you're squashing some unrelated ideas together here.

certainly. The issue isn't really simple.

|> J does not provide an anomalous syntax for comments, but that doesn't
|> mean comments need to be cumbersome.

I think it does. With lamp, you can put anything you want afterwards, 
such as 

<lamp> ' )why not.

I agree with L.J. Dickey that the generality to do this is desirable
and useful. If language syntax controls what you can put as a comment,
I would say that's cumbersome. The only way comments can be completely
arbitrary is if they are anomalous language elements. I'd guess this
is proved in introductory progamming language design courses. I don't
know and don't have a formal proof (I'm an M.E.), but it sounds like
an interesting logic problem. 

|> First off, it helps to have a few tools to write programs with.  One
|> technique is to use an editor to build your objects, and save
|> everything in a workspace.  Another is to build scripts which read
|> objects in from standard input (that is, the script).

If you don't use readable scripts that can be changed by some completely
external editor, aren't you in trouble when the language changes (like 
2.9 -> 3)? Can J 3.0 read a 2.9 ws? (I know this is another unrelated 
subject).

|> Second off, there are quite a number of useful quoting techniques.
|> The first of which is to organize your program carefully.  Also, using
|> descriptive names helps a great deal.  

Another unrelated subject: J uses x. and y. for arguments. Undescriptive.
One technique I sometimes use is to immediately set

   xlabel=. x.
   location =. y.

or some such. I find this somewhat unappealing as it looks inefficient, 
especially if used in some inner routine (called by many others). 
A kludge.

> Also, for some verbs, it helps
|> to have a block comment at the begining (or end), to orient the
|> reader.  

I agree. I do that.

>And then, you can always adopt a style where you have
|> comments describing individual lines of a program (usually, you set
|> off both the comments and the described lines with blank lines).  

Another good style I agree with.

|> And,
|> finally, you can do "running narrative" tricks like:
|> 
|> a =. ['step one'] here is a calculation
|> b =. ['step two'] here is another
|> 

Doesn't this look aesthetically unappealing? Two (or 3) comment characters? 
Looks kind of like a kludge to me. Especially if you have contractions, 
embedded quotes etc. which some comments will have.

|> I don't know if it is possible to come up with a "perfect" comment
|> syntax (for example, in C you have to be careful when you divide by a

I don't like C's comments for the reasons you mention. On the other hand,
I find APL's (lamp) perfectly acceptable.

|> J's
|> comment style has the advantage of making comments proper objects of
|> the language (which makes the language itself somewhat simpler, and
|> allows the user much more flexibility than some sort of pre-processing
|> kludge).

One person's kludge might be another person's efficient solution. For
example one language element (lamp) versus two or three([]'). I think
that the designers of J took a "theoretical" approach rather than a
"practical" approach. This leads to many advantages, but some
dissadvantages.

Comments are an important issue. One serious criticism of APL is that
the code is "impossible to read." I think the criticism is somewhat
undeserved since: 

- small sections of APL may in fact be much easier to read than equivalent 
  sections of other languages due to compactness,

- one can always choose to write readable code, for example deliberately 
  separating things onto seperate lines, adding comments liberally...

I'd rather have the freedom to do what I want instead of having the
language impose readability ("structured languages") on me. J seems to
me to be taking the other extreme, making it harder to add comments
and write readable code. This is admittedly a subjective judjement.
I'ts not a comdenation of J, as I still admire the language overall,
and especially admire its availability.


-- 
Sam Sirlin
Jet Propulsion Laboratory         sam@kalessin.jpl.nasa.gov

