APL readability

Question

I need to encode APL. Since the code will be maintained for a long time, I wonder if there are any documents / books that contain heuristics / tips / samples to help develop clean and readable APL programs.

This is a different experience than coding in another programming language. Creating a function, for example. Small does not help: such a function may contain one line of code, which is completely incomprehensible.

Answer 1

First, welcome to the beautiful world of APL.

Writing readable and supported APL codes is not much different than writing readable and supported code in any language. Any good book on writing clean code applies to the APL like any other language, perhaps even more so. I recommend Robert C. Martin's Clean Code.

Consider the manual in this book that all code in a function must be at the same level of abstraction. This applies to APL 100 times. For example, if you have a function called DoThisBigTask, it should have very few primitive APL characters and, of course, not too complex single-line characters. It should just be a series of calls for other lower level functions. If these higher-level features are well known and well defined, the overall drift should be easily determined by someone who does not even know the APL. The functions of the lowest level will be nothing but primitives, and will be incomprehensible to non-APLers. Depending on how they are written, they may even seem incomprehensible to an experienced APLer. However, these low-level functions should be short, have no side effects and can be easily rewritten, and not changed, if the supporting programmer cannot understand the original coding technique.

In general, keep your functions short, well-named, well-defined, and precise. And keep the lines of code shorter. It is much more important to have well-defined and well-documented functions than to have well-written or well-documented lines of code.

Answer 2

Since you requested books and other references, I can suggest:

• APL2 in the depths of Norman D. Thomson and Raymond P. Watering. I worked with Ray Polivka for many years and he was one of the best APL teachers I ever knew.
• Classic A.P. L.: Interactive approach Leonard Gilman and Allen J. Rose are good for the main language, but it is quite outdated and does not contain much, which is really relevant for readability.
• APL 2 at a glance James A. Brown and Sandra Pakin serves in some ways as an update for Gilman and Rose. It covers nested operations and other updates for the APL, but does not have a specific indication of readability. However, if you follow the examples here, you will write readable code.
• APL Easy by STSC, and Jerry R. Turner is an intro specifically designed for the APL * Plus line. Again, there is not much specific readability, but models are usually well-designed readable code.
• Mastering Dyalog APL: A complete introduction to Bernard Legrand's Dyalog APL is not bad if you specifically work in Dyalog APL, not so much if you work in one of the other versions, such as APL * Plus (from APL2000)

I believe that the reputation of APL as a "write-only language" is greatly overstated. You need to get used to the primitives and symbols that are used to represent them. But then you need to get used to the syntax and various library functions in many other language environments. I have seen convoluted code in C, C ++ and Java, as hard to follow as any APL. Of course, this is not good for C, C ++ or Java, even if it is smart.

Some tips:

• Writing "single-line" is a way to test one language proficiency, but it is very unsatisfactory practice for production code.
• Commentary to make the algorithm and especially used data structure clear. As with any code, comments should add something that cannot be easily read from the code itself or draw attention to complex or obscure code.
• If possible, avoid obscure code, so there is no need to explain it. This is usually possible.
• Make each function one and only one task with a clear interface. Avoid global variables for the most part and document everything you need.
• Document the interface, purpose and effectiveness of any function on the Top. Make utilities black boxes without side effects, if possible. If side effects are necessary, document them as part of the interface. Design a standard heading comment structure.
• Dynamic code built in on the fly can add flexabiliy to the solution, but it is often harder to debug if problems arise. Make the code bulletproof to the extent possible, and create optional logging to help when you still have problems.

If you wish, you can use a style similar to OOP. But there is no need to do this. If you do this, then IMO will be used quite widely through the application, with the possible exception, for low-level utilities. But OOP style code can be at least as complex as non-OOP code, and the APL does not have built-in inheritance or other syntax that supports OOP.

Answer 3

(I will use "A" here instead of the comment, "" instead of the character.)

---

Well, I developed APL for a year, I used Aplusdev.org .

You don’t even need anymore. The trick is to try and think about OOP-like . You should have - if I remember well - structured fields used as class data , sth, for example {'attribute1' attribute2, {value, value2}}, so you can easily select them as obj.attribute1 in C ++. (here 'Pick object attribute, use only in classes :) :)

Also use functions with names:

 namespace_classname.method(this, arg1) namespace_classname._private_method(this, arg1, arg2) 

and many simple tool functions instead of great long lines. The performance degradation is not significant, you can optimize later to say arrays as soon as you see that something can be faster.

And above all: I think that matlab and mathematica are without loops! :) This helps a lot.

My suggestions for reliable, supported code:

• use an extended set of utility functions instead of cheating with these unreadable characters so your code is always at the point.

• try-catch blocks there is a built-in exception handling that can be used here,

  try_begin ();
  Tried code, possibly in extra brackets, so as not to forget try_end () at the end.

  try_end ();
  catch (sth, function_here);

  can be well implemented. (You will see that the error trap is very important)

• raw type checking : implement the standard and use for functions called so many times ... (you can put a function with flexible parameters right after defining the function) <w> Syntax:

  function (point2i, ch): {
  typecheck ({{'int, [1 2]},' char}); And to make some statements in typecheck ...
  // Your function goes here
  }

• lambda functions can be very effective, you can do some thought to achieve lambda.

• always declares a return indicating "return"!

• Testing devices based on the try-catch test of each function you write.

• I also used a lot of “ apply ” and “ map ” from math, implementing my own version, they are very effective here.

• I wrote MATLAB thinking, since here you can have a list of structured fields (= class data) in a variable. You will write a lot of these if you want to keep things without a loop (and you want, believe me). To do this, you need to have a standard naming convention indicating with multiple values:

  namespace_class.method (objects, arg1, arg2)

To the end: I also wrote an inputBox and messageBox, like those in Javascript or VisualBasic, they will be very easy to crack simple tools or state checks. The only catch of messageBox is that it cannot pause the stream function, so you need to

  AA documentation of f1 f1(): { A do sth msgbox.call("Hi there",{'Ok, {'f2}}); } f2(): { A continue doing stuff } 

You can write auto-docs in bash using the gawk / sed combination to put it in a web page. Also creating HTML code helps with printing .;)

I hope it was a good plan for building up properly. Before writing your own tools, try digging out the available tools from an outdated code base ... functions are often even 4 times implemented with different names due to the mess of the time.