Scannability in Scripting

Posted by John Mathewson on July 17, 2020

What is Scannability?

Scannability is an attribute of any written piece, including FileMaker scripts, that help the reader find pertinent information quickly.

Why is High-Scannability in scripting important?

  • Easier and faster way to understand the purpose and actions of the script
  • Reduced errors in comprehension of the code and recollection of the specifics
  • Reduced strain on developer’s focus

What does High-Scannability look like?

It is a clear naming convention for scripts, which looks like:

You will also find a detailed purpose/notes, clear sections of scripts, business logic details, and effective comments.

What does Low-Scannability look like?

Below is the same script without all of the above elements discussed. Consider the difference in time spent between the Low-Scannability version and the High-Scannability version. Try to imagine these different scenarios considering the difference in the two:

  1. Report to the user what the logic is for deleting time sheets.
  2. Re-enable this schedule on FileMaker Server after installing a new FMS version. Determine which day of the week to set it up for.
  3. As a developer seeing this for the first time, determine the purpose and expected result of this script.
  4. Debug an issue when creating time sheets (especially if they are not properly linked to an appointment).

What practices should developers employ to ensure their code has a High-Scannability level?

It all starts with this: Adopt the perspective of a future developer. Assume this future developer is lacking any knowledge of business logic or any other elements of the code base.

From here, make sure your code meets the following criteria:

  1. The script is easy to find within the workspace; follows clean naming convention.
  2. The purpose of the code is explicitly stated at the top.
  3. Any parameters for the script are explicitly stated.
  4. There are clear “Sections” of the script.
  5. Any calculations that are beyond the “basic” level have commenting, which can detail the expected result(s).
  6. All business logic should be commented throughout the script where applicable. The future developer should not draw questions or have to make assumptions.