Latest revision as of 01:02, 6 April 2017

Target Audience

For the sake of argument, I will pretend that the people who will benefit from the use of metapatterns fall into two distinct groups: software developers and non-software developers.

Of course, the reality is not that clear-cut and many people will be firmly footed into both groups.

Bridging The Gap

Creating good scripts to automate graphics-orientated programs like InDesign, Illustrator... is not quite the same as general software development.

In general software development, most times the people viewing software source code will be software developers or engineers.

They share a large amount of background knowledge that does not need to be communicated.

Properly written source code written by one engineer can be read and understood by another engineer. They understand the basic rules of software development, and there is no need to re-iterate what is common knowledge between them.

It's not a simple situation. There are many often mutually conflicting schools of thought around 'proper' software development, and two software engineers will often disagree on what is 'best practice'.

But they'll understand what the other rules are, even if they don't agree with them. One engineer might prefer indentation with spaces, the other might prefer tabs (an eternal debate that will never be settled).

When it comes to writing scripts for graphic workflows, the situation is even more complex. Often a software developer is involved, but at the same time, a non-software developer will be involved too. For example, a graphics designer might want to tweak some existing script to better match their workflow.

In that case the different actors do not necessarily share an understanding of what rules there might be.

When a non-developer reads a script written by a software developer, a lot of detail will escape being noticed.

This web site is an attempt to bridge that gap.

It allows a software engineer to clearly communicate to a 'consumer' of the software what they need to pay attention to, and to highlight important aspects in a standardized way.

It allows a graphics-orientated person to understand important details about a script without needing to get a degree in computer science.

Metapatterns

Metapatterns are remedies and approaches for specific issues surrounding scripting and programming in general.

In most programming literature, these are commonly referred to as ‘patterns’, but I’m referring to them as metapatterns, for two reasons:

• I managed to register the domain name metapattern.info to house the online metapattern info web site
• The word ‘pattern’ is an overloaded word with other meanings. By referring to 'patterns' in the realm of software development as 'metapatterns' it avoids possible confusion with, say Illustrator fill patterns.

How to use metapatterns

Software Developer

As a software developer, you will know many or most of these patterns. A few of them might be new to you, and could be useful to you.

You can choose to follow one or more of these metapatterns when you create scripts. You have total freedom in what you want to pick, but the more patterns you follow the higher your chances that someone further down the track will be able to understand and make good use of the software.

If and when you choose to follow the metapattern approach, you will add some standardized comments to your script. This to clearly communicate which metapatterns you had in mind when building the software.

Of course, these metapatterns are merely suggestions. You can make up your own mind how rigorously or how loosely you want to apply any of them, if at all.

Also keep in mind that a lot of these metapatterns will seem incredibly obvious, to a software developer, that is.

It is important to keep in mind that they are not necessarily obvious to a non-developer.

Non-developer

As a non-developer (e.g. a graphics designer, a layout artist...) you might find a script that almost does what you want, but not quite.

The first thing you would do is to open the script in a text editor and look for comments left by the software developer.

If you're lucky and/or my attempt at establishing a common ground succeeds, you'll find a list of metapattern codes.

You would then use this web site to look up each pattern to understand what it is about.

If the original creator of the script followed any of these patterns, you’d be able to adjust the script to some extent, hopefully right up to the point where it does what you need.

Metapattern Codes

Software developer are encouraged to provide metapattern codes with their scripts.

Each of the metapatterns in this wiki has an optional alphanumerical code.

The idea is that the software developer can list these codes near the beginning of the script.

Later on, anybody wanting to use the script can very quickly find out what to expect simply by consulting the codes. Example codes:

• READABLE
• ALPHABETIZE
• VERSIONED
• ...

For example, a script could have the following information near the start:

  // This script adheres to the following metapatterns:

  //

  // http://metapattern.info/READABLE      Readable Script

  // http://metapattern.info/ALPHABETIZE   Alphabetize functions
  // http://metapattern.info/REGULAR_TABS  Uses spaces instead of tabs

  // http://metapattern.info/LOGS          Has optional error logging code

If you notice a metapattern code that you are unfamiliar with, and you want to know more about it, you can paste the URL shown into your browser address bar and read up on it.

After just a brief glance on the metapattern codes, you gain a lot of knowledge about how the script is structured.

That helps you to go about configuring the script for your own purposes, or making changes to the script.

A lot of the metapattern codes will be irrelevant to the end-user or consumer of the script. It’s up to the script developer to decide whether to list them or not.

For example, a metapattern code like LONG_INDEX is something you want to keep in mind while developing a script, but it’s not too relevant for the script’s consumer.

You still might want to list the metapattern code if you anticipate that someone else will take your script as a starting point for a future new script.

Having the metapattern code explicitly listed will help them build a new script in the same ‘spirit’.

More info on the metapattern codes can be found in the ‘Metapattern Codes’ discussion.

Text Editors

JavaScript and ExtendScript files are text files, and you can (and should) open them with a text editor.

To make efficient use of this wiki, you need a good text editor.

Because there are so many, I decided to select just two free text editors, and I’ll use these throughout the wiki (e.g. when making screenshots).

On Mac, I’ll use TextWrangler (http://www.barebones.com). It is very powerful in its own right.

Personally I don’t normally use TextWrangler; instead I use its big brother, BBEdit, also from Bare Bones.

TextWrangler is free; BBEdit is not free; it is a much enhanced version of TextWrangler. I highly recommend BBEdit, but for working through this wiki, TextWrangler will be just fine.

On Windows, I’ll use the free Notepad++ (http://notepad-plus-plus.org).

You can also use the basic Notepad editor that comes with Windows, but using NotePad is not too much fun.

Notepad++ has a lot of ‘script-friendly’ features that NotePad lacks.

I don’t recommend using Microsoft Word or TextEdit (which is a freebie that comes with the Mac OS).

It is all too easy to accidentally re-save a pure text file in some non-text format (for example, RTF). And that makes the script unusable.

As a general rule: when re-saving a script after modifying it with a text editor, make sure you did not accidentally save into a different file format. If a script suddenly starts misbehaving, make sure you did not accidentally convert it to, say, RTF file format.

A second ‘gotcha’ is that sometimes people accidentally re-save a script with a .txt extension.

For example, the original file might be myscript.jsx, but after opening, it’s accidentally re-saved as myscript.jsx.txt.

Computers are often configured not to show certain filename extensions. As a result, the file might seem to be called myscript.jsx because the trailing .txt is not shown.

End result: the script will look OK, yet refuse to run. If you have a stubborn script that misbehaves, make sure there is no hidden extension causing problems.