🚀 go-pugleaf

I would be interested in commenting styles for APL that people have found
useful.  APL has somewhat the reputation for being a "write only"
language, but I feel that the problem lies more with inadequate commenting
technique.  If, say, a line of APL can do the work of a page of another
programming language, it may be inappropriate to try to describe the
activity of that line in only one or two lines of comments.

The technique I have found that works best for me is to follow
complicated APL lines with a comment line of "pointers," followed by
more comment lines explaining what is happening at each pointer.

Example:

      ................................ (line of apl code)
     "A      B       C        D
     "D: FIND FIRST 'K' ON EACH ROW OF MATRIX, THEN
     "   ROTATE EACH ROW TO EACH BRING FIRST 'K' INTO THE
     "   FIRST COLUMN.
     "C: ROTATE EACH COLUMN BY INDEX OF LETTERS FOUND ALONG
     "   THE MAJOR DIAGONAL OF THE MATRIX.
     "B: ROTATE THE COLUMNS AGAIN, PUTTING THE 'K'S IN THE
     "   FIRST COLUMN BACK INTO THEIR ORIGINAL POSITIONS.
     "A: PUT THE RAVEL OF THE MATRIX INTO 'TEMP' FOR USE
     "   IN THE MERGE COMING UP


One problem with this technique is that whenever the code line is
edited, the pointer line must usually be adjusted to make sure that the
letters still point to the correct places.  But I have found this to be
a small price to pay for the benefit of being able to comment about the
intermediate processing going on within the line.  Since comment
lines are exdented one character automatically, it is possible to point
to any part of the code line, including the leftmost character.

What other useful commenting techniques are people using on the net?

George Otto
Bell Labs, Indian Hill