はじめに
このガイドラインは個人的観点から作成されています。
ワークフローアナライザーを使いたい場合は公式のコーディング規約に準拠した方がいいと思います。
思いついたら不定期に内容を更新していきます。
用語説明
| 用語 | 説明 |
|---|---|
| アクティビティ | 自動化処理を作る時に使用する部品のこと。 クリック(Click)、文字を入力(Type Into)など |
| コンテナ | 内部にアクティビティを持つことができるアクティビティのこと。 「ブラウザーにアタッチ(Attach Browser)」アクティビティなど。 |
| プロセス | アクティビティを組み合わせてまとめたもの。 xamlファイルのことを指します。 |
| コード | プロセスの別名。 説明上、あえてコードと表現する場合があります。 |
| ワークフロー | UiPath Studioで作成した自動化処理のこと。 プロセスを組み合わせたものがワークフローです。 UiPath Studioではプロジェクトと呼ばれます。 |
| メインプロセス | ワークフローの流れを制御するメインのプロセスのこと。 ワークフロー内にメインプロセスは1つだけ存在する。 |
| サブプロセス | メインプロセスから呼び出されるプロセスのこと。 |
| プロセスルート | xamlファイルの一番最初にあるアクティビティのこと。 「シーケンス」、「フローチャート」、「ステートマシン」のどれか。 |
| スコープ | ある変数の名前（識別子）を参照できる範囲のこと。 |
| グローバル変数 | スコープがプロセスルートにある変数 |
| ローカル変数 | スコープがプロセスルートより小さい変数 |
| セレクター | UI 要素を選択するためのパス（住所のようなもの） |
| 完全セレクター | 最上位の要素を含めた完全なセレクター |
| 相対セレクター | 最上位の要素は含まないセレクター |
| 動的セレクター | 一部を変数またはワイルドカード(*, ?)に置き換えたセレクター |
| idx属性 | セレクターに含まれるUI要素のインデックスを表す属性 |
| ロボット | UiPath Robotを指します。 ワークフローを実行するためのツールです。 |
| スタジオ | UiPath Studioを指します。 ワークフローを作成するためのツールです。 |
ネーミング規約
全般
● 略語は使わない
| 良い例 | 悪い例 |
|---|---|
| password | pw |
| separate | sep |
| count | cnt |
| directory | dir |
| credentials | cred |
※ 公式に定めている略語や広く一般に知られている略語は例外
(USA, NASAなど)
● 汎用的な名前は使わない
例：tmp, number, flag, counter
● 原則英語を使う
ただし、いくつかの例外がある。
ユビキタス言語が他言語の場合、英訳しにくい言葉など。
変数
● 変数はスネークケース
例：product_code, customer_name
● アルファベット1文字の名前を使わない
例：i, j, kなど
ただし、スコープが狭い場合は使ってもよい。
● 名前に情報を詰め込む
変数の値を推測しやすい名前にします。
| 良い例 | 悪い例 |
|---|---|
| login_id | id |
| email_address | address |
| product_code | code |
※ str, intなどの型情報は不要です。
● 明確になるなら、変数名は長い方が良い
短くて分かりにくい変数名より、長くても分かりやすい変数名の方が良い。
● スコープが広い場合、長くて具体的な変数名が良い
スコープが広い場合、短い名前や抽象的な名前は衝突するリスクが高い。
● スコープが狭い場合、短い変数名でも良い
スコープが狭い場合、名前の衝突が起こるリスクは低く、長い変数名を付けるメリットが少ない。
● boolean変数はtrue/false の状態がわかるようにする
変数名に適切なプレフィックスを付けることで状態がわかりやすくなる。
| プレフィックス | 用途 |
|---|---|
| is | 〇〇であるか |
| has | 〇〇を持っているか |
| exits | 〇〇が存在するか |
| can | 〇〇をできるか |
定数
● 定数は全て大文字、_ で区切る
例：ACCESS_KEY, TIMEOUT_LONG
● 定数は変数パネルの規定値で宣言する
● 定数をプロセス間で共有する場合は、引数として渡す
定数を書いた設定ファイルを用意することは良い選択です。
しかし、その設定ファイルを読み込んだDictionary型変数などをそのまま引数に渡したり、その設定ファイルをサブプロセスで読み込むことは良くない選択です。
そのプロセスに必要な定数だけを個別に引数として渡しましょう。
引数
● 引数はスネークケース
例：url, id, password, token
● 引数名は短くシンプルにする
可能な限り1つの単語に抑える
● _ を付けての区別は禁止
| 良い例 | 悪い例 |
|---|---|
| value | _value |
| id | id_ |
| password | _password_ |
● 引数の方向で「入力/出力」は禁止
引数の方向は「入力」と「出力」だけ使う。
アクティビティの表示名
● 必ず規定の名前から変更する
「クリック」、「文字を入力」、「代入」など既定の名前だけでは検索がしづらい。
● 「既定の名前 要素を表す言葉」で名前を付ける
例：「ブラウザーを開く ログイン画面」、「文字を入力 ログインID」、「クリック ログインボタン」
xamlファイル名
● ファイル名はパスカルケース
例：SystemLogin.xaml, FileDownload.xaml
● 抽象的な名前を付ける
使用するシステムやファイルの名前、画面IDなどの具体的な情報はファイル名にいれない。
例：UploadFile.xaml, FetchStockQuantity.xaml
● ファイル名は短くシンプルにする
1～3つの単語に抑える。
● ファイル名には動詞を含める
プロセスが何をしているのか端的に表した動詞をファイル名に含める。
ディレクトリ名
● ディレクトリ名はパスカルケース
例：Util, BusinessRule, UseCase
● ディレクトリ名は名詞を付ける
システム名称、ユビキタス言語、アーキテクチャ上の呼称など具体的な名詞を付けると良い。
● ディレクトリ名は短くシンプルにする
1～3つの単語に抑える。
コーディング規約
UI操作
● アクティビティはバックグラウンドで実行可能な状態にする
「クリック(or 入力)をシミュレート」プロパティを有効にする。
動作しなかった場合、「ウィンドウメッセージを送信」プロパティを有効にする。
● 文字入力は「文字を入力(Type Into)」アクティビティを使う
「入力をシミュレート」、「ウィンドウメッセージを送信」のどちらかを有効にしていない場合、IMEの影響を受けることを考慮する。
動作しない場合は、他アクティビティを使っても良い。
● プルダウンメニューの選択は「項目を選択(Select Item)」アクティビティを使う
動作しない場合は、他アクティビティを使っても良い。
● 「ユーザー入力をブロック(Block User Input)」アクティビティは使わない
ロボット実行を途中停止させることが困難になるから。
● スクレイピングはヘッダを含める
ヘッダを含めない場合、列の名前が「Column-1」となってしまい変更に弱くなる。
ヘッダが無い場合、変更箇所を最小限に抑えるため、スクレイピング直後にヘッダを変更します。
セレクター
● 完全セレクターを使わない
完全セレクターはシステム変更に弱くなる。
「ウィンドウにアタッチ(Attach Window)」、「ブラウザーにアタッチ(Attach Browser)」などの一部コンテナ系アクティビティは例外。
● 変数を使った動的セレクターは原則禁止
変数を使った動的セレクターは動作保証が取りにくい。
ワイルドカード(*, ?)を使った動的セレクターは可。
● idx属性は禁止
idx属性がセレクターに含まれている場合、システム変更に弱くなる。
idx属性を使いたい場面においては、「子要素を探す(Find Children)」アクティビティなど代替え案を考える。
制御
● 条件分岐の条件式は「可変値 比較演算子 固定値」にする
左→右に視線が誘導されるので、可変値は左、固定値は右にあると見やすい。
● 「繰り返し (後判定)(Do While)」アクティビティは使わない
条件式が下にあるため、可読性が悪い。
● 条件分岐、繰り返し系のコンテナに多くのアクティビティを入れない
可読性が下がる要因となります。
また、処理が無駄に複雑になります。
コンテナ
● 原則、コンテナの中に別のコンテナを入れてはいけない
「ブラウザーにアタッチ(Attach Browser)」、「繰り返し (コレクションの各要素)(For Each)」などのコンテナ内に別のコンテナがあるとネストが深くなり、可読性が下がる。
ブラウザーが表示するアラート（ポップアップ）など、仕方ない場合はコンテナ内にコンテナを入れても良い。
プロセス
● 1つのプロセスにはシンプルな作業を1つだけ行わせる
システムにログインする。
検索画面に指定条件を入力して検索ボタンを押す。
など、シンプルな作業を1つだけ行わせるようにします。
● プロセス内のアクティビティ数を少なくする
アクティビティ数が10個以下であれば理想的です。
読みやすいコードを心がけましょう。
コメント
● 不要なコメントは書かない
コードからすぐに読み取れる内容は冗長になるので書かない。
名前（変数名など）の説明は書かない。
コメントに書くのではなく、わかりやすい名前に変える。
コードに関係ない内容は書かない。
コメントアウトされたコード、修正履歴、バグ情報は不要です。
ソース管理システム、バグトラッキングシステムなど別システムで管理しましょう。
ライセンスは書かない。
ライセンスファイルをプロジェクトルートに作りましょう。
● コピーライトは書かない
コピーライトは法的拘束力を持たないため、原則不要とする。
ただし、記載が必要な場合は各プロセスに記載します。
プロセスのルートとなっている「シーケンス」、「フローチャート」、「ステートマシン」のコメントに書くことをお勧めします。
● プロセス全体に関わる内容はプロセスルートに書く
プロセス全体に関わる内容の例を下に挙げる。
・プロセスの説明
・引数
・戻り値
・例外
・TODO
● フォーマットは統一する
コメントのフォーマットは可読性を上げるため、プロジェクト毎に統一する。
おわりに
いいなと思ったらLGTMよろしくお願いします。
ストックして頂ければ変更通知が届くようになります。
ぜひ皆様のプロジェクトでご活用ください。
誤字脱字、内容の不足があれば編集リクエスト頂けると幸いです。