Tom Larsen blogs about the more technical aspects of audit analytics using ACL software. In his latest post he discussed some of the things that annoy him about trying to interpret other ACL users’ styles. What do you think? Do you agree with Tom’s list of no-nos?
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 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 NewTable
Field1
Field2
Field3
Field4
Field5
Field6
The 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.
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 realised 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 favour 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.
Do you agree with Tom? What would you like to see done differently or change?
