Aihuxi.126 net.lang.apl utzoo!decvax!harpo!ihnss!ihuxi!otto Thu Apr 8 22:40:11 1982 Commenting APL code 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 ----------------------------------------------------------------- gopher://quux.org/ conversion by John Goerzen of http://communication.ucsd.edu/A-News/ This Usenet Oldnews Archive article may be copied and distributed freely, provided: 1. There is no money collected for the text(s) of the articles. 2. The following notice remains appended to each copy: The Usenet Oldnews Archive: Compilation Copyright (C) 1981, 1996 Bruce Jones, Henry Spencer, David Wiseman.