Latest revision as of 02:47, 6 April 2017

Readable Scripts

Metapattern Code: READABLE

For Graphics Designers

The first measure of readability of a book or magazine is the content.

Well written, concise content is more readable than rambling drivel.

Nearly as important as the content is the layout and formatting.

Good layout and formatting entices the reader to continue reading, and helps the eye stay on the trail of the content.

If a script carries the READABLE metapattern code, it means that the software developer has paid attention to make the script code readable.

You’re invited to read the whole script, and not just the documentation or header comments.

The script’s ExtendScript code is meant to be self-explanatory, and the script should rate high on the ‘pokeable’-scale.

However, just like with layout, the ‘look and feel’ of readable scripts will vary greatly between different software developers.

The main idea is that the script is easy to follow, and is formatted using consistent rules, while leaving the actual styling up to the personal taste of the software developer.

As a script reader, you need to be aware that when the computer executes a script, it will be ‘jumping’ all over the script.

Most scripts are divided up in smaller chunks of code, called 'functions'. Most functions have a name which is meant to be indicative of what they accomplish.

Most scripts will start by executing some code somewhere.

This initial starting point is not always at the top. It might be found somewhere in the middle or even near the end of the script.

If you try to follow the logic of a script, you’ll often find yourself jumping backwards and forwards through the script code in order to see how various steps in the script are built up out of smaller steps.

If the MAIN metapattern is applied, the script starts with an initial function called Main(), and then the script will branch off from there, into more specific operations.

If the ALPHABETIZE metapattern is applied all the functions are listed in alphabetical order, making it a bit easier to find them.

If you have a text editor with script support (like TextWrangler or Notepad++) you can also use a popup menu provided by your text editor to quickly jump from one function to the next.

See the Appendix - Reading and understanding a script for more info.

For Software Developers

A script that will be shared with others should be readable.

Scripts that consist of a clump of dense code are not readable.

A conscientious developer will spend time polishing the script until they can make its internal workings and methods almost self-evident.

Most times, a script should be written with a human reader as the first concern, and the computer executing it only as a second concern.

Some pride themselves in being able to create code that reminds me of an English fruitcake made with non-self-raising flour: dense, unreadable code which works great for the computer, but is not easy for humans to digest. This is often described as 'Write Once, Read Never' code.

In 'the olden days' doing this could prove to be useful. Computers were not very powerful, and a developer had to help things along as much as possible. ‘Clumped code’ often worked faster.

Nowadays the difference in execution speed between ‘clumped code’ and ‘airy, readable code’ is most often negligible from the perspective of the user. No user cares whether something that takes 0.1s to complete is optimized to take 0.01s.

Of course, there are always situations where highly optimized, clumped code makes sense, but they are far and wide between.

Given that CPU time is cheap, and people-time is expensive, you want to invest a lot of effort into making the script readable.

Speed of execution is only very, very rarely an issue. Judiciously choosing algorithms and data structures has much greater influence on the speed than hand-optimizing code.

As a side benefit, making a script more readable forces the script developer to think about it a bit harder, and in the end, making a script more readable has the unexpected side-benefit of making it more efficient and more bug-free as well.

Detailed description of the metapattern

Whitespace is free, and its impact on performance is totally negligible. Use it to help the reader.

A typical script is composed of a number of functions.

Use judicious spacing and add comments to visually highlight related items in the code.

Visually separate the functions from one another.

How exactly you do that is a matter of personal taste, but keep the LIGHTWEIGHT_VISUALS metapattern in mind.

Within the functions you typically have one or more areas that I think of as ‘phrases’.

A phrase consists of one or more JavaScript/ExtendScript statements that together reflect a single ‘thought’.

Again, use white space to separate the phrases.

If ExtendScript statements can be thought of as ‘sentences’, then ExtendScript ‘phrases’ can be thought of as ‘paragraphs’.

A few sentences make up a single paragraph. A few statements make up a single ExtendScript phrase.

Use a consistent formatting style. There are many formatting styles.

Pick one, or make up your own. The style itself does not matter. Just make sure it is consistently used, throughout the script. If your style is not a common garden variety, make sure to document it somewhere and point the reader to this documentation.

This affects things like

• visually balancing the curly braces ({ ... })
• formatting of long expressions in some way whether to keep lines short
• format your loops
• ...

Rename variables, functions, function parameters and constants so they clearly indicate what they do.

Do it as concisely as possible.

During development and testing it’s OK to use short, cryptic variable names.

Afterwards, some time should be spent replacing any cryptic or ill-advised variable names with carefully selected names that reflect the meaning and function of each variable, function or constant.

Try to reduce the number of comments as much as possible.Yes, I said reduce - read REDUCED_ROT for more info.

It is better to rename a variable, and not need to add a comment than to leave an ill-chose variable name and having to add clarifying comment.

Comments in a script occur for a number of reasons:

• something is genuinely difficult, not obvious, or hard to follow, and it really needs extra explanation. In that case, a comment is warranted. (good)
• explanations for sloppy code (not good). Made-up example:

// i is the offset in the character code table
// we start at unicode 2103 (degrees celcius) and 
// go up to 2109 (fahrenheit)
for (var i = 2237; i < 2284; i++) {
...
}

could be something

for (var charCodeTableOffset = gCharCodes.UNICODE_CELCIUS; charCodeTableOffset < gCharCodes.UNICODE_FAHRENHEIT; charCodeTableOffset++) {
...
}

• re-stating the obvious (very bad)

// Here we assign 7 to i and then call the function f2
i = 7;
f2(i);

The script developer must work a bit harder to make the script so readable that the comment can be eliminated.

Superfluous comments that ‘state the obvious’ should simply be removed.

Add extra variables and functions to break up complex sequences or long expressions (CONSTANT_FLUFF, VARIABLE_FLUFF and FUNCTION_FLUFF).

Ask other people to read and try and understand your script.

Keep in mind: style is personal. If you're the original author of a script, no-one should meddle in how you like your braces balanced, or whether you prefer comments with // instead of /*...*/or whether you prefer spaces or tabs.

However, try testing your style on unsuspecting victims and make sure your style is readable without undue effort or coaxing.

As Yoda said: to a style religiously sticking does not readable your code make.

Related metapatterns

 ALPHABETIZE
 INTRO
 LINE_END_CRLF
 MAIN
 REDUCED_ROT
 REGULAR_TABS