FileMakerの命名規則（自己流）

# はじめに
FM-1グランプリへの投稿作品を作り始めたのは、FM-1グランプリの存在を知る前からだったのですが、その時に、最初に検討を始めたのは命名規則でした。もともとのんびり作ろうと思っていたので、いろいろな情報を集めながら、FileMaker自体はあまりいじらず、メモ帳に思いついた命名規則をちまちま記録していました。このQiitaの記事は、自身の備忘録用、今後の更新記録を残す（？）目的で作成しました。自分自身に対しては「こうすべき」との戒めも含まれますが、個人開発者の個人利用目的なので、他人に強制する要素は一切ありません。

# 命名規則を考える上で大事な法則
自らの性格・能力に因るもの。

- 命名規則に限らず、規則はつい忘れてしまう。
    - 略称は、元の言葉を簡略化する「規則」によって行われるので、可能な限り使わない。
    - 忘れてもすぐに確認できる状態がよい。
- 命名規則を確認するのは面倒くさい。
    - すぐに目に着くところに命名規則が記載されてないと、正しく適用できないことが増える（マイナーバリエーションができてしまう）。
    - 命名規則が適用される場所で、命名規則が確認できるようにする。
- 直感に合わないと効率が悪くなる。
    - 入力キーバインドが難しいものや、見た目が直感的でないものは、コーディングの効率を悪化させる。
    - 将来の自分を含む他人にはそのままでは理解できない可能性が高い。ファイル上で説明されているとよい？

# FileMakerの命名規則を考える上で必要な情報
- FileMakerで名前を設定する要素。
    - テーブル名、テーブルオカレンス名、フィールド名、スクリプト名、レイアウト名、レイアウトオブジェクト名、変数名、カスタム関数名、カスタム関数引数名、値一覧名、外部データソース名、テーマ名、スタイル名、アクセス権セット名、メニューセット名、メニュー名。
    - ウインドウ名は、ユーザに見せるラベルみたいなものなので、規則の対象外。

- フィールド名等の文字数の制限がある。
    - 100文字まで。
    - 自己環境で調べたもの。いずれの名前も100文字を超えるとアラートが表示されて入力できない。
    - ヘルプでもごく一部の名前にしか、この制限は書かれていない（仕様とかに書いてあるといいのですが）。
- フィールド名等で使えない文字がある。
> •フィールド名には次の記号や単語を使用しないでください。
> •, (コンマ)、+、-、*、/、^、&、=、≠、>、<、( )、[ ]、{ }、"、; (セミコロン)、: (コロン)、:: (リレーションシップ記号)、$ (変数記号)
> •AND、OR、NOT、XOR、True、False、および FileMaker Pro の関数名
> •計算式で使用されるフィールド名の先頭文字には、スペース、ピリオド (.)、数字を使用しないでください。
> •ODBC、エクスポート、Web 公開、およびその他の処理の制限を回避するために、スペースの代わりに _ (アンダースコア) を使用してください。

出典：[フィールド名の指定](https://help.claris.com/ja/pro-help/content/naming-fields.html?Highlight=フィールド名) 

- フィールド名だとアラートが出ても、とりあえず入力はできる。計算式で使うと`${}`でラップされる。
- フィールド名以外では、どのような禁則があるかは不明。スクリプト名なら`->()`あたりは使っても怒られない。
- 上記から推定される使える記号
  - `_%#.@~|!?¥`

# FileMakerの命名規則に関する記載がなされているサイト
命名規則を考える際に参考にさせていただいたサイト達。日本語でまとめられているサイトはなかった（残念！なので自分で記事にしてみた）。

- [filemakerStandards.org](https://filemakerstandards.org/display/cs/OverView)
    - たぶん一番よくまとまっている。ここでいろいろ学ばせていただいた。英語。
- [dbservices.com](https://dbservices.com/blog/filemaker-naming-conventions-and-standards)
    - 英語。
- [AppWoks](https://app.works/the-impact-of-naming-conventions-on-code-readability/)
    - 英語。
- [うさぎのメモ帳](https://usagi-mimi.com/blog/AboutFileMaker/entry-311.html)
    - フィールド名だけについてですが、思想は参考になる。日本語。
- [p388cell](https://medium.com/@p388cell/coding-standards-9d6822c972c9)
    - ここら辺のご意見をいただいて、自己流の命名規則を考えるに至った。日本語。
- [Apple Coding Guidelines for Cocoa](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/CodingGuidelines/CodingGuidelines.html)
    - FileMakerに絞ったものではないが、その哲学はホントに参考になると思う。
    - ちょっと古い。最近のAppleからは、このような情報開示が少ないように感じます。
    - 英語。

# FileMakerの命名規則（自己流）
## 基本ルール
- 上記法則により、命名規則は可能な限り、実際に使用するところに記載しておく。
    - 具体的にはファイルの中で、下記記載場所一覧のところに個別に記載しておく。
    - ファイル内に記載することになるので、仮に将来、命名規則を変更しても、該当ファイルを読み解くには問題が少なくて済む？
    - つまり、この記事はあくまで備忘録的まとめ。

- 上記法則により、可能限り略称は使わない。
    - 例外は、`ID`とか`JSON`とかぐらいかな？

### 記載場所一覧

|  命名標的  |  記載場所  | 
| ---- | ---- |
|  ファイル名、外部データソース名 |  リレーションシップグラフ内  |
|  テーブル名、テーブルオカレンス名  |  リレーションシップグラフ内  |
|  値一覧名  |  値一覧  |
|  フィールド名  |  フィールド<br>HubテーブルのfKey_xJoint.numberフィールド内にコメント記載  |
|  スクリプト名  |  スクリプト  |
|  カスタム関数、カスタム関数引数名  |  カスタム関数  |
|  変数名  |  スクリプト・カスタム関数（どちらでも頻用するので2か所に記載）  |
|  レイアウト名、テーマ名、スタイル名  |  レイアウト  |
|  アクセス権セット名 　|  アクセス権セット  |
|  メニューセット名  |  カスタムメニューセット  |
|  メニュー名  |  カスタムメニュー  |
値一覧、スクリプト名、カスタム関数、レイアウトについては、命名規則の記録用にダミー項目を作成し、その中に記載しておく。

- 基本はUpperCamelCaseで。
    - 積極的にセパレーターとして`_`を用いる。つまりSnake_Caseでもある？
    - ハンガリアン記法（識別子）も使う。
    - 日本語使用を否定しない。FileMakerのよい特徴でもあるし。
    - いいとこ取りをする。

## ファイル名・外部データソース名
- データベース名~サブカテゴリー_機能{`Administrator`, `Interface`, `Processor`, `Data`}
    - 「機能」は分離モデルの使用をイメージ。
- Gitを使えばバージョン管理は必要ないが、必要があれば、作った日付を接頭辞としてつける（例えば`20211123_`）。
- 外部データソース名は、該当ファイル名の接頭辞に`e_`をつけたもの。

## テーブル名・テーブルオカレンス名
### テーブル名
|  接頭辞  |  意味  | 例  |
| ---- | ---- |---- |
|  D_  |  データ管理<br>Data  | D_DatabaseName  |
|  F_  |  設定値、既定値<br>Fixed  | F_Values, F_Graphics  |
|  M_  |  管理用<br>Manage  | M_dummy, M_Hub  |
- テーブルオカレンス名と違うことを認識する意義が大きい。

### テーブルオカレンス名
|  接頭辞  |  意味  | 例  |
| ---- | ---- |---- |
|  なし  |  管理用  | dummy, Hub  |
|  S_  |  Hubからセレクトされたもの<br>Selected  | S_TableName, SF_TableName, eS_TableName  |
|  A_  |  HubにxJointで接続しているもの<br>Anchor  | A_TableName, eAF_TableName  |
|  B_  |  アンカー、ブイにつながっているもの<br>Buoy  | B_Anchor~Buoy#Condition  |
|  e  |  外部データソース  | eS_TableName, eA_TableName, eB_Anchor~Buoy  |
- アンカー・ブイモデルについては[こちら](https://guantare.com/2019/02/02/post-932/)辺を参照。
- テーブルの親子関係に`»`（右ギユメ）を使うのもよく見るのですが、ちょっと入力しずらい。簡単に入力できて、つながっているイメージから`~`を使用。英語だと簡単に入力できるのかなぁ？
- `dummy`は、データなしレイアウト用。特殊テーブルなのでUpperCamelCaseにしていない。
- `Hub`テーブルには、カルテシアン（デカルト積）結合させる`fKey_xJoint.number`フィールドを設定。コネクター、セレクターの役割を持たせる（セレクター・コネクターモデルについては[こちら](https://notonlyfilemaker.com/2015/03/selector-connector/)辺を参照）。
 
## フィールド名
### リレーションキーにするフィールド
- 主キー
    - `_serialID.number`
    - `_UUID.number`
    - 数字、索引設定済（Unicode）、自動入力、値変更不可、常に検証する、ユニークな値
    - 接頭辞の`_`はシステムだけが使用することを示唆している。
- 外部キー
    - key_親テーブル名~そのプライマリーキーフィールド名
    - `key_ParentTableName~serialID.number`
    - `key_ParentTableName~UUID.number`
    - 子テーブルで設定。親のプライマリーキーが一意に定まり、変更しない場合に用いる。
    - `keys_`：Values形式でキーを用意する場合
    - `gKey_`：グローバルキー

### その他のフィールド

- 接頭辞の`_`はシステムだけが使用することを示唆する。
    - `_trigger.boolean`

|  接頭辞  |  意味  |    |
| ---- | ---- | ---- |
|  g_  |  グローバルフィールド  | global |
|  r_  |  繰り返しフィールド  | repeating |

以下の接頭辞は排他的になる。
|  接頭辞  |  意味  |    |
| ---- | ---- | ---- |
|  c_  |  計算フィールド  | calcuration |
|  u_  |  結果を保存せず必要時に計算  | unstored calculation |
|  a_  |  計算値自動入力  | autofill |
|  l_  |  ルックアップ自動入力  | look-up |
|  f_  |  固定値（計算値で固定してしまう）  | fixed |
|  s_  |  集計フィールド  | summary |
|  w_  |  処理用  | working |
|  qq_  |  不使用、削除予定  | quit |

接頭辞は併用が許容されるが、下の接頭辞が排他的であるので、実質的には、gとrとその他の最大3文字となる。すべて小文字で連結。ただし、たとえばgとuはシステム上排他的なので、併記されることはない。記載順は原則、ここでの表の上から順に記載していく。

例
`gc_`：グローバルフィールドの計算値。
`grf_`：グローバルフィールドで繰り返しフィールドの固定値。

|  接尾辞  |  意味  |
| ---- | ---- |
|  .text  |  テキスト  |
|  .number  |  数値  |
|  .date  |  日付  |
|  .time  |  時刻  |
|  .stamp  |  タイムスタンプ  |
|  .container  |  オブジェクトフィールド  |
|  .boolean  |  ブーリアン型、実態は数値  |
|  .json  |  JSON形式、実態はテキスト  |

Values（値一覧）形式で、数値や日付を羅列している場合には、それぞれの接尾辞に複数形のsをつけるが、実態はいずれもテキスト形式になる。

- `.texts`, `.numbers`, `.dates`, `.times`, `.stamps`, `.booleans`
- Values形式のデータから、要素取り出し時に形式変換に注意する。

- データ形式をフィールド名には入れない方がよい、と言う意見もあるようだが、FileMakerではリレーション時に、この形式の違いで引っかかることが多いので、フィールド名でそれを判別できるのは非常によい。
- データ形式を接尾辞にしたのは、ファイル名での拡張子のイメージ。最後を見ると形式が何かが分かると言うのは、自分的にはかなり直感的。

## レウアウト名・テーマ名・スタイル名
### レイアウト名
- 処理・機能等@テーブルオカレンス名#使用するウインドウスタイル.形式
  - ウインドウスタイルは、通常のドキュメントウインドウの場合には、符号はつけない。他のは以下のとおり。

|  符号  |  スタイル  |
| ---- | ---- |
|  #float  |  フローティング  |
|  #dialog  |  ダイアログ  |
|  #card  |  カード  |

- `ShowList@DataTable.table`
- `ShowForm@DataTable#dialog.form`
- 該当ファイルのスクリプト内でのみ使用される場合は、接頭辞に`_`をつける。基本的にユーザが使用しないもの。
- `_Manage@Hub.form`
- `_Summary@DataTable.table`

|  接尾辞  |  表示形式  |
| ---- | ---- |
|  .form  |  フォーム形式  |
|  .list  |  リスト形式  |
|  .table  |  テーブル形式  |

### テーマ名
- 現状では、テーマの使い分けにあまり意義を感じていない。
  - 1つのファイルで使い分けすると表示パフォーマンスが改善したりするのか？
- なので、名前はインスピレーションで。

### スタイル名
- 「デフォルト」は消去できない。
- オブジェクトの種類ごとにカテゴライズされるが、カテゴリを超えても同じ名前は許容されない。アラートが出る。
- 選択時に表示できる文字数に限りがあるので、接頭辞に種類をつけるのは無駄。
- 接尾辞をつけることで種類別で名前が重ならないようにする。

|  接尾辞  |  種類  |
| ---- | ---- |
| .part  |  パート  |  
| .line  |  線  |  
| .shape  |  形成
| .edit  |  編集ボックス  |  
| .drop  |  ドロップダウンリスト  |
| .popup  |  ポップアップメニュー  |
| .calendar  |  ドロップダウンカレンダー  |
| .container  |  オブジェクト  |
| .text  |  テキスト  |
| .buttonbar  |  ボタンバー  |
| .button  |  ボタン  |
| .portal  |  ポータル  |
| .image  |  グラフィック  |
| .web  |  Webビューア  |
| .graph  |  グラフ  |
| .tab  |  タブコントロール  |
| .slide  |  スライドコントロール  |

### レイアウトオブジェクト名
- UpperCamelCase#識別子
    - 識別子は基本数字でよいと思っている。
- 必ず設定しなければならないものではない。通常無名でよい（と思われる）。
- レイアウト上に同じオブジェクト名があるとよくない。そのための識別子。

### レイアウト作成時のtips  
#### Windows, Macで共通で使用できるフォントのおすすめ
|  フォント名  |  形態  |
| ---- | ---- |
|  Verdana  |  サンセリフ体・プロポーショナル  |
|  Times New Roman  |  セリフ体・プロポーショナル  |
|  Courier New  |  セリフ体・等幅  |

サンセリフ体・等幅で、共通に使えるデフォルトフォントはなさそう。必要なフォントが追加できるなら問題ないが。

## 変数名
|  接頭辞  |  変数種類  | 例  |
| ---- | ---- |---- |
|  $  |  ローカル変数  | $localVariableName  |
|  $$  |  グローバル変数  | $$GLOBAL.VARIABLE.NAME  |
|  %  |  Letステートメント変数、関数の引数  | %letVariableName  |

- 言うまでもないが、FileMakerでローカル変数、グローバル変数での接頭辞はシステム要件。自身では調整できない。
- Letステートメント変数は、参考サイトなどで、接頭辞に`~`（チルダ）をつけて表現されるのが潮流とは学んだのですが、自分にはどうしてもしっくり来ず、`£`（ポンド記号、`$`と同じ通貨記号でLet関数の頭文字とも合致）や`#`（ハッシュ、元は重さの単位ポンドを表し、`£`に通ずる）も検討して、最終的に見分けやすさを優先して`%`を選択。
- ローカル変数、Letステートメント変数は、lowerCamelCase。接頭辞の記号を目立たせるため。
- グローバル変数の表記は、[参考サイト](https://filemakerstandards.org/display/cs/Variable+naming)から。グローバルの変数の管理法は[こちらの記事](https://qiita.com/siebenunddreissig/items/144fa0e2abdbf1519719
)で記載しているので、そちらを参照。この管理法のおかげで、コーディングの時にグローバル変数を実際に入力することは、あまりない。
- 計算式で、`=`は、変数への代入のみに用いて、同等比較の場合には、極力Exact関数を使う。
  - 見間違いを防ぎ、可読性を上げるため。
  - パフォーマンスもわずかだが、Exact関数の方がよい。
  - Case Sensitiveにしない場合でもUpper関数、Lower関数を利用してExact関数を使用する。

## スクリプト名
- 動詞\_名詞{目的語}\_条件等(#引数;引数2;...)->#結果1;結果2;...
  - Swiftの関数をイメージ。
  - スペースは使わない。
  - 引数や結果が1つの場合には値そのままでJSON形式にはせず`#`もつけない。
  - 引数や結果をJSON形式で渡す場合に接頭辞に`#`をつける。複数引数、複数結果であっても`#`をつけるのは先頭の1つのみ。
  - `Find_Records(#Word1;Word2)->ResultList`
  - `Show_Layout(WindowName)`
    - 結果の部分は、結果を返さない、あるいは必ず`True`なら省略してもよい。
- 接頭辞`_`
  - 該当ファイル内のスクリプト内でのみ使われる場合に指定する。 
  - 基本的にユーザーが直接使用することはない。
  - 外部スクリプトを実行するときに、外部で使うことを想定していないことを端的に示す。
- 接頭辞`button@Layout_`
  - ボタンで用いられるスクリプトのときに指定する。
  - どこで使われるボタンがはっきりしているならレイアウトも指定しておく。
  - 汎用ボタンならレイアウトは省略してよい。
- 接頭辞`w_`
  - 作業用
- スクリプトの先頭には、以下のようなコメントを入れる。
    - 製作者、製作日、修正日なども記載した方がよい、との意見もあるが、今のところ、あまり必要性を感じていない。
    - 上記はFileMaker側で管理してくれてもよさそうに思う。
    - 記入形式は、この記事を書きはじめて体裁を整えた。以前はタブを使っていたので、努力の割に見栄えがよくなかった。

```JAVA:_Move_WindowOf(#WName;ToTop;ToLeft)->IsExist
# ======================================================================
# Purpose
#   ウインドウをアニメーション付きで移動させる。
# Parameter
#   JSON形式
#   [ #WName; JSONString ] = Window Name
#   [ #ToTop; JSONNumber ] = 目標となる上位置
#   [ #ToLeft; JSONNumber ] = 目標となる左位置
# Return
#   ウインドウを移動できたらTrue、対象ウインドウがなく新規ウインドウ作成したらFalse
# Notes
#   ウインドウの選択はされない。
#   加減速にシグモイド関数を使用している。
# ======================================================================
```


## カスタム関数名
- UpperCamelCaseで、スクリプト名のような`_`でのセパレートは極力しない。
- 引数名は%lowerCamelCaseで。
    - Letステートメント変数と区別をつける必要はないと考えていますが・・・。
- 引数の部分も含めて文章として分かるような関数名にする。
    - `GetFileNameFrom ( %filePath )`
- グローバル変数の管理用関数は、`Set.` `Get.`を接頭辞とする。
    - ドットをつけることで、ドットセパレーターを用いているグローバル変数を想起させる。
    - グローバルの変数の管理法は[こちらの記事](https://qiita.com/siebenunddreissig/items/144fa0e2abdbf1519719
)で記載しているので、そちらを参照。
- スクリプトの返り値作成用には、`return_`を接頭辞とする。
- 定数もカスタム関数で指定してしまう。
    - コーディング時に自動補完が効いて、可読性も上がる。
    - 空（から）データを表すものとして`nil`。関数の計算式には何も記載しない。
        - nullでなくてnilにしたのは、Swiftでのイメージから。
        - nilは空（から）そのものを意味しており、nullは空（から）の状態を意味している、みたいな解説もあった。
    - 通常の定数は接頭辞に`@`。
        - その場に固定しているイメージ。
        - Errorコードや、モードを表す数値なども、カスタム関数で定数にした方が可読性がよい。
        - `@ErrorCode_WindowIsMissing`
        - `@Mode_Browse`
 
    - JSONに用いるキーは接頭辞に`#`。
        - データに紐づけるタグのイメージ。
        - スクリプトの引数としても、`#`でJSONをイメージさせる。
        - スクリプトの引数として多数用いるとスクリプト名の文字数制限にひっかかることも。そのため、このJSONキーの名前だけは、省略形を積極的に使用している。
- カスタム関数の先頭には、下記のようなコメントを入れる。
    - 製作者、製作日、修正日なども記載した方がよい、との意見もあるが、今のところ、あまり必要性を感じていない。
    - 上記はFileMaker側で管理してくれてもよさそうに思う。


```JAVA:Set.IsFileOpened&nbsp;(&nbsp;%boolean&nbsp;)
// Purpose
//   $$IS.FILE.OPENEDを設定する。
// Parameter
//   %boolean = これまでにファイルが開かれていなければnil、開かれていればTrue。
// Notes
//   結果は必ずTrueを返す。
```

## 計算式内の記載について（スクリプトやカスタム関数で関わりが多い）
- インデントは半角スペース2文字にする。
    - タブだと入力しずらいのと（option/ALTを押す必要がある）、Windows、Macで表記がずれるため、避けた。
- `;`セパレーターの前にはスペースは付けない。
    - 引数の場合には、`;`の後ろに半角スペース1文字。
    - 計算式の行末を表すなら、`;`の直後で改行する。
- `( )`や`[ ]`の前後には半角スペースを1文字入れる。
- 演算子（`+`, `-`, `*`, `/`, `^`, `and`, `or`, `=`, `<`, `>`,...）の前後には半角スペースを1文字入れる。
- テキストデータとして、`¶`マークはダブルクォーテーションで挟む必要はない。当然ながら、テキストデータの中に入っているものをわざわざダブルクォーテーションの外に出す必要もない。
- Let関数の記載法（インデントの付け方）

```JAVA:
Let ( [
  %variable = Function ( %parameter );
  %variable2 = Value
];
  return
)
```
- While関数の記載法（インデントの付け方）

```JAVA:
While ( [ initial setting
];
  condition; [
    logic
  ];
  return
)
```
- 初期設定のところが1行で済む場合には、`Let`、`While`が表記されている行に記載してしまう(While関数の記載法の例のごとく)。
- Let関数で、変数設定が1つの場合には`[　]`は省略できるが、省略してもパフォーマンスは変わらない？　[こちらの記事](https://qiita.com/siebenunddreissig/items/144fa0e2abdbf1519719)も参照。 
  - 少なくとも、可読性やメンテナンス性（後で変数を追加したいときなど）では、`[　]`が付いていた方がよいと思われる。


## 値一覧名
- フィールド値を使用している場合
    - テーブル名~フィールド名（最後に`s`をつける）#機能等
    - `TableName::serialIDs#FieldName`
- カスタム値を使用している場合は、接頭辞に`f_`をつける。
    - `f_ValuesName`
- 外部データソースを参照するものは接頭辞に`e_`をつける。
    - `ef_ValuesName`, `eA_TableName::FieldNames`
- 命名規則を考えてから、あまり値一覧を作成していないので、実用性の判別がつかない。

## アクセス権セット名
- タイトルケース。
    - 基本の単語は大文字で始め、冠詞、接続詞、前置詞等は小文字にする。詳しくは[ここ](https://www.sanctio.net/capitalization/)を参照。
    - `Title of Privilege Sets`
    - `For Normal User`, `For Administrator`
- 標準のアクセス権セット名(英語版)は`[Full Access]` `[Read-Only Access]` `[Data Entry Only]`。基本にこれに合わせる。

## メニューセット名
- タイトルケース。
    - 基本の単語は大文字で始め、冠詞、接続詞、前置詞等は小文字にする。詳しくは[ここ](https://www.sanctio.net/capitalization/)を参照。
    - `Title of Menu`
    - `Normal Use Menu`, `Minimum Menu`
- メニューバーのツール→カスタムメニューで表示選択されるものなので、他のメニューと同じような表示になるようにする。
- 標準のメニューセット名(英語版)は`[Standard FileMaker Menus]`。基本にこれに合わせる。

## メニュー名
- #組数-メニュー番号_表示名（タイトルケース）
    - メニューバーに表示される順序等を判別しやすくするために、数値でラベル付けしておく。
    - 組数はメニューの種類分けをイメージして。実際には複数組を作るに至っていない。将来的になくす？
    - メニュー番号は、標準メニューとして表示される順で番号付。ただし、標準のメニューバーに表示される順番とは異なっている。これも番号付けを考え直した方が良いかも知れない。
    - 標準の表示タイトル（英語）は、`FileMaker Pro`, `File`, `Help`, `Records`, `Requests`, `Insert`, `View`, `Edit`。特別な理由がなければ、これを利用する（実際のメニュータイトルはデフォルトにする）。

# サンプルファイル
カスタムApp作成時の元ファイルとして、こんなものを用意している。参考までに。
<a href="https://github.com/siebenunddreissig/OnlyNamingConventions"><img src="https://github-link-card.s3.ap-northeast-1.amazonaws.com/siebenunddreissig/OnlyNamingConventions.png" width="460px"></a>