Originally published 2017-10-20 on blog.tlarsendataguy.com, and shared here with permission.
By my reckoning, my last blog post was in July, which means I have now missed 2 monthly posts. I apologize for that. Since July I have made the huge decision to accept employment with a new company and move myself and my family from Wisconsin to North Carolina. Now that the move is completed and I have begun working for my new employer, I hope to resume my normal monthly posting schedule.
On account of my starting a new life, I do not have a whole lot to talk about. So today I am going to focus on something that has been bothering me for quite some time: I have trouble reading ACL code, and the enemy is us. We seem to be good at writing unreadable code, but as scripters, readable code should be a top priority for us. Our code is the only product we have to offer, and it should be as well-designed as we can make it.
I generally try to take the attitude of ‘live and let live’ when it comes to scripting styles. But some things objectively make our code harder to read. Here are some of those things, with the most negatively impactful ones first:
- Command and function abbreviations. I do not know who was under the influence of what when the decision was made to allow abbreviated commands and functions, but it was a terrible decision. I know of no other language that allows abbreviations of its commands and functions, and if another does exist, I will be sure to never try it…ever.
- Skipping lines in conditional computed field definitions. What exactly is this?
DEFINE FIELD MyCategory COMPUTED
'A' IF SomeField = 1
'B'
The lines starting with ‘A’ and ‘B’ belong with ‘DEFINE FIELD’…why in the name of all that is good on this earth are they physically separated from DEFINE FIELD by whitespace? This code looks like 3 separate commands, not 1 command. I have seen this everywhere, and I still cannot read it efficiently. Something needs to link these two sections, and ACLScript provides the ‘AS’ parameter. Use it. Preferably indented.DEFINE FIELD MyCategory COMPUTED
AS 'MyCategory'
'A' IF SomeField = 1
'B' - Excessive nesting. As you know, functions can be nested in ACL. This is great, because we can combine several operations into 1 logical line of code. However, once you get to the 3rd or 4th level of nesting, it becomes very tedious understanding what is actually supposed to be happening. The amount of time I have spent trying to decode nests of functions 5 or 6 layers deep is significant, and all of it non-value added. If you find yourself nesting 3, 4, or more functions, you are trying to do too much work on 1 logical line of code. It is ok to take 2 or 3 lines to do what you want to do; there is no award given for the largest nested function.As a side note, this is one of the biggest roadblocks I have with reading R, Clojure, and other languages which were inspired by Lisp.
- Whitespace. Speaking of whitespace and indenting, some of us spend way too much time hitting the ‘return’ key. If you have more than 1 blank line separating ‘sections’ of your code, you have too many. Alternatively, if you never add a blank line to your code, then I refer you to this handy diagram on locating the return key on your US English keyboard:
How often should we add blank lines? That, my friend, is up to you. As long as you are somewhere between no blank lines and blank lines everywhere, I can appreciate your effort. As for me, I generally group various commands into ‘tasks’ which perform a specific action, and separate these ‘tasks’ with blank lines and a leading comment. I would say, on average, I have 4-8 lines of code in each ‘task’. This might be an example of a ‘task’:COMMENT Add standard cost to the sales order line items so we can calculate margin
OPEN SalesOrderLines
OPEN StandardCost SECONDARY
JOIN PKEY Material FIELDS ALL SKEY Material WITH StdCost PRESORT SECSORT TO CostedSalesOrderLines OPEN
CLOSE SECONDARY
Commands like EXTRACT, GROUP, LOOP, DEFINE FIELD, etc which can be on multiple lines should be indented. Indenting is an excellent way to group the related elements together. Each indent only has to be 2 spaces to be visually effective. - The EXTRACT command allows for us to list the fields we are extracting on separate lines. So an EXTRACT command that looks like this:
EXTRACT FIELDS Field1 Field2 Field3 Field4 Field5 Field6 TO NewTable
Can also be written like this:EXTRACT FIELDS TO NewTableThe latter syntax is much easier to read, particularly with large field listings. If you have a choice between the command being large horizontally or vertically, I would encourage you to write it vertically.
Field1
Field2
Field3
Field4
Field5
Field6 - Over-formatting comments. Here is one to make your life easier. ACL’s script editor formats comments as green. There is no need to go overboard with formatting comments. Leave the asterisks, dashes, and underscores at home. If you are leaving a single-line comment, just write it after the COMMENT (not COM) command:
COMMENT This is a comment
Don’t unnecessarily add blocks of comments when single-line comments work. This is too much:COMMENT -----------------
COMMENT This is a comment
COMMENT -----------------
Even if you only incorporate the first 2 items into your style, the readability of your code will improve by at least 42%. Not only will this benefit anyone who reads your code, but it will also benefit you 6 months in the future when you have to go back and decipher your own scripts. I have not arrived at these observations arbitrarily; many of them I have violated in the past and realized that they made it harder to quickly regain my understanding of past code. I have also been influenced from the styles of other languages such as Python, R, and C#, where readability can be much more crucial and much easier to destroy. So let’s do us all a favor and start thinking about how our code will look 6 months from now rather than focusing on getting the code written as quickly as possible today.
Responses