Final Thoughts on Documentation

FileMaker Extra: Soliant Development Standards

For this final section of the book, we've opted to provide for your consideration the standards our own custom development service firm, Soliant Consulting, uses. We do not want to be guilty of thinking that our coding standards are the only ones available, and if the struggle we had internally to arrive at a single standard is any indication, we're very cognizant that other approaches are entirely valid and effective. The important point in all of this is to adopt a standard any standard. On the other hand, we felt that a chapter on documentation and standards would be incomplete without presenting at least one concrete set.

Please know these standards are presented largely in their day-to-day undigested form without a great deal of exposition or details on the rationale behind the choices we and our organization made.

If you are interested in learning more about FileMaker standards, or in delving further into an excellent exploration behind why some of these decisions have been adopted, we strongly recommend you read the document that FileMaker Inc. itself has published on the topic (available free as a PDF download). To get to the FileMaker Development Conventions, go to the following site:

http://www.filemaker.com/products/upgrade/techbriefs.html

The authors of this book participated in the development of the FDC tech brief and believe that it serves as a comprehensive guide to standards in FileMaker.

Furthermore, in these standards we present the "Anchor Method" of managing the Relationships Graph in FileMaker. Roger Jacques, the initial creator of this approach (and a senior manager at Soliant), published an article, "Managing the FileMaker Pro 7 Relationship Graph," explaining the thinking behind the method in the September 2005 issue of FileMaker Advisor Magazine . An electronic version of that article is available, along with archives of all the magazine's articles, as a subscription service on the FileMaker Advisor website:

http://www.filemakeradvisor.com

We recommend that you include a copy of whatever standards you've used with a given solution so that a new developer to the project can review them if you are unavailable for whatever reason.

These conventions are compliant with version 1.0 of the FDC standards published November 1, 2005.

Required Conventions

All conventions in this section are required in order for a file or files to adhere to the Soliant coding and development standards.

Naming Conventions

Files

• Filenames may use only the characters AZ, az, 09, and _ ( underscore ) and must begin with a letter. Spaces are not allowed, but InterCaps can be used to distinguish words.

• Files from one solution need to have a common prefix so that they sort together, even if there is only one file. For example:

  cbi_IndigoMain.fp7, cbi_Agents.fp7 , and so on

Tables

• Table names may use only the characters AZ, az, 09, and _ (underscore) and must begin with a letter.

• Prefix developer tables with "z_"for example, "z_Globals," "z_Resource," and so on.

• Always sort tables by name .

• Tables should always be named for the descriptive entity in question. In other words, for example, use "Invoice" instead of "Table3."

• Singular or plural naming convention is optional, but must remain consistent throughout the applicationfor example, Employees and Departments, or Employee and Department.

FIELDS

• Field names may use only the characters AZ, az, 09, and _ (underscore) and must begin with a letter (with the exception of keys; see the subsection "Key Fields").

• Developer fields (except keys): Always prefix with "z_" and only "z_". No other prefixing. Use an optional suffix for more detail if you want (see the "Recommended Conventions" section later in this document). Spaces are not allowed in developer fields, but InterCaps can be used to distinguish words on object names. For example:

  z_FlagInvoicePaid

  z_TempError_gn (note the global denoted in the optional suffix)

• Always sort fields by name.

Key Fields

• All fields used in relationships must be identified as keys with a "_k*_" prefix. For example:

  _kf_contact_n (contact foreign key)

• For primary keys we use two underscores to ensure that the field sorts to the top of the list. For example:

  __kp_contact_n (contact primary key)

• Only keys used in primary data relationships should be considered foreign keys. For the rest, use the following:

  _ka_SelectedContactName_t (alternate key)

  _kc_contactOrg_ct (compound key)

  _km_contact_t (multiline key)

  _kg_contact_gt (global key)

• The prefix "_k*_" means that keys will sort to the top of an alphabetized list of fields.

• Only kp and kf are mandatory designations, the rest are optional.

Housekeeping Fields

• All tables must have the following four housekeeping fields:

  z_recCreateAccountName

  z_recCreateTimestamp

  z_recModifyAccountName

  z_recModifyTimestamp

"Temp" Fields Rule

• Any field that contains the word "temp" in it makes no assumptions about its contents except within a single script routine (that may also comprise nested scripts). At the end of a script, a temp field can be considered empty or over-writable.

• Note that FileMaker 8 introduced script variables. It is often no longer necessary to use temp fields for the purpose of storing variables ; we have left the rule in the standards for those systems still in place using older versions of FileMaker.

Layouts

• Layout names may use only the characters AZ, az, 09, and _ (underscore) and must begin with a letter.

• Layout names need to make use of a prefix to indicate the "Anchor table occurrence (TO)" to which they are attached. (See the later section "Table Occurrence Naming" to understand what an "Anchor TO" is.) For example:

  EMP_EmployeeList
  COM_CompanyPopUp
  

• Layouts from the same Anchor TO should be grouped together in layout order.

• Any developer layouts should be prefixed with a z_ .

Script Names

• Script names may be divided into functional groups. If so, the standards make no prescription as to what those groups should look like. (Sorting scripts might constitute one functional group , navigation scripts another.)

• If functional groups are not used, scripts must be ordered alphabetically .

Version Control

• Version control for client deliverables should be managed via an enclosing folder name, not via changes to the filenames.

• No specific folder naming scheme is mandated . It could be alpha/beta/final, or it could be a simple timestamp.

• All compressed archive filenames should be formatted in the timestamp method. Time indication is optional as military time, or AM/PM for morning or afternoon.

• Version control applies to archived files, not individual FileMaker files or their surrounding folders. You need to apply the timestamp convention only when you compress/archive the project folder. For example:

  AcmeCRM_2005_03_15.zip
  Indigo_2005_03_16_PM.sit
  ApricotEBP_2005_03_17_1500.tgz
  

Scripting Comments

We encourage liberal script comments, but these are the minimum requirements:

• All scripts will include three headers that identify the purpose, dependencies/variables, and edit history of a script. Each developer who edits a script will insert an ID line similar to this:

  Purpose: Navigate to Contacts Layout

  Dependencies: (examples: layout name for context, script parameters, script variables, or plug-in requirements)

  History: scl 2004 jan 01 (helpful to put the day last for quick editing)

• End each script with an Exit Script script step. This allows the logic of the script to conclude while leaving Script Debugger open . It also serves to explicitly demonstrate an end to the routine.

Script Parameters

• All script parameters should be identified in the script comments as dependencies.

• The script parameter delimiter for multiple parameters should remain consistent throughout the application.

• Any delimiter other than a hard return can be used.

Script Results

• If the script returns a result, the nature and meaning of the result should be documented.

Script Variables

• Any global variables used should be listed as a dependency with expected initial state and resultant state at the end of the script.

• Optionally describe local variables as well.

Relationships Graph

• We have opted to standardize on the "Anchor Method" style for our systems. These are the primary reasons for this:

  • To help when selecting layout objects from a list dialog of table occurrences

  • To make the Relationships Graph itself more manageable/comprehensible by other developers

  • To make a meaningful naming convention possible

• In this scheme, those TOs linked together form a Table Occurrence Group (TOG) with one Anchor TO at the leftmost position.

• A TOG must be a complete island; there may never be a relationship line between any two TOGs.

• All other TOs in the group exist for the purpose of feeding related data to the Anchor TO.

• All user layouts should be associated only with an Anchor TO. Developer layouts used in scripts for establishing context, populating sample data, and so on may be based on any TO. Any layout that a user sees must be based on an Anchor TO.

• TOGs and TOs are read, and meaningful, from left to right. Even though the FileMaker Relationships Graph is bidirectional, the TOs are arranged hierarchically for clarity. The naming convention mentioned in the text that follows creates a similar hierarchical effect in pop-up dialogs.

• Some source tables may have multiple TOGs where they serve as an anchor. The decision to create a new TOG is based on functional requirements. Some examples follow:

  • Data needs to be fed to a set of list/detail screens.

  • An Anchor table is used in two functionally different ways, and each requires its own TOG.

  • A UI screen requires a source table; a TOG is based on a developer table.

Figure 27.7 shows a typical TOG.

Figure 27.8 shows the same information that's included in the list of TO names used in a number of dialogs within FileMaker. Note that they order themselves hierarchically just as they appear on the Relationships Graph.

Table Occurrence Naming

The name of a TO describes the chain of source tables between the anchor and the TO itself, with optional attribute indicators. The attribute indicators can be functional names, names of keys, or any other means of clarifying the purpose of the TO. The ability to read a chain of TOs in both the graph and the various pop-ups and dialogs lends clarity. By reading the name of a single TO, one should be able to grasp where on the Relationships Graph it sits.

These are the rules that govern TO naming:

• All TOGs start with an anchor. An anchor is named in the following fashion:

  DIS__District__tog (or anchor)

• The first occurrence of an abbreviation is cappedfor example, DIS .

• The double underscore makes the anchor sort to the top of all lists.

• The corresponding source table name is title casefor example, District .

• The __tog attribute indicates that this TO is the anchor for a TOG. You can optionally use __anchor if you'd like.

• Subsequent TOs start with the TOG name, but in lowercase:

  dis_LIB__Library__valuelist

• The leftmost TO name is the anchor; the TO above is part of the DIS TOG.

• The source table is indicated by the capped abbreviation LIB . All lowercase TOs are connected, and the single capped TO is the associated source table.

• The second element of the name, following two underscores, is the familiar name of the source table entity: Library .

• The optional attribute is the functional description: __valuelist .

• After an abbreviation for a source table has been established, it must remain consistent throughout the graph.

• Some developers use the optional suffix to list the keys used in establishing relationships to table occurrences. The InventoryItem table occurrence in Figure 27.7 might also be named:

  dis_lib_ITM__InventoryItem__kf_Library

• Abbreviations are used to save space: FileMaker Pro on Windows truncates TO names in several dialogs. Three character abbreviations are typical, but the length of the abbreviation is at the discretion of the developer. The only hard and fast requirement is that names are legible on Windows .

Recommended Conventions

The conventions in this section are not mandated, but they provide some standard ways of doing certain things, if you choose to do them.

Coding Practices

• Calculation Dialog Comments:

  • Insert comments in the first line of a calc that are readable in ScriptMaker and Field Definitions windows:

    If [//
    
    this condition is true
    
    //]
    Set Field [//
    
    describe set value
    
    //]
    

• Liberally add comments to complex scripts and calculations. Use whitespace for legibility.

• Use the Let() function where you would have more than one or two nested functions.

• Reuse of Code:

  • Modular coding of scripts and use of subscripts.

  • Script parameters for reusable scripts.

  • In cases in which an array is used in a script parameter, write custom functions for parsing data into and out of the array.

Naming Conventions

General Practices

Keep your names as short as reasonably possible. Some dialogs are still width-restricted in FileMaker on Windows.

Fields

We use InterCaps for multiple words. Underscores are meant to differentiate between elements of a field (or table) name; however, user fields make an exception to that rule, where effort should be made to support ease of reading for end users.

• Use grouping of names to organize fields:

  Address_City

  Address_Street1

  Address_Street2

  Name_First

  Name_Full_c

  Name_Last

• Optional suffixes for all developer fields:

  • First character (or characters in combination) as special field:

    g (global)

    s (summary)

    r (repeating)

    c (calculation)

  • Second (or last) character as data type:

    n (number)

    t (text)

    d (date)

    i (time)

    m (timestamp)

    r (container)

Examples of developer fields that follow these conventions look like this:

• z_MainLogo_gr (global container)

• z_SortPreference_gt (global text)

• z_ColumnSortIcons_grr (global repeating text)

• z_recCreateModDisplay_ct (calc text)

Script Names

Scripts may be subdivided into functional groups and separated by a header. Additionally, insert a single hyphen to appear as a separator. For example:

-
------------- FILE MANAGEMENT
OnOpen
OnClose
Relogin for testing
-
------------- ADMIN ACCOUNT FUNCTIONS
Create New Account
Delete Account

Spaces are acceptable in script names. Keep in mind that on Windows, some dialogs open only to approximately 4050 characters.