【Power Platform】オリジナルのコーディング標準を作ろう（後編）
こんにちは。システムソリューション営業本部の吾妻です。
「【Power Platform】オリジナルのコーディング標準を作ろう」シリーズの後編として、Power Platform製品群を対象とした自社独自のコーディング標準を用意する際に、抑えておくべきポイントについてご紹介します。
前回の記事では、「コーディング標準」資料を用意しておくことのメリットや、コーディング標準を作成する前に検討しておくべき事項をご説明しましたが、今回は、実際に弊社で作成しているコーディング標準を例に、どのようなことを記載するか、どのように運用・改訂していくかをご紹介したいと思います。
執筆・運用体制
一般に、コーディング標準を検討・作成したり、その後の運用のなかでガバナンス面での管理を実施したりするのは、Power Platform製品を導入・構築する IT部門 や（各部門より選抜されたメンバーからなる） プロジェクトチーム になります。
これらの体制において、コーディング標準を検討する際のメンバー構成として、大人数で合議制としてしまうと、個々人の慣れや嗜好の違い、世の中の流行に引きずられてなかなか規約を決められなくなりがちです。
このため、コーディング標準を作成した後にトップダウンで組織内に展開しやすいように、決定権のある人を巻き込みながら、少人数で進めた方が上手く進むように思います。
ただし、そうした個人の嗜好による規約の取捨選択はなるべく排除しなければならないので、信頼できる公開資料を基に作成したり、過去に取り組んだ案件での実装を抽出したりすることで、できる限り普遍的な内容となるように心掛けます。
余談ですが、コーディング標準の整備と同様に、市民開発コミュニティの運用においても、レビューや監査に関与する人数が増えれば増えるほど、アジリティが低下して、市民開発者の満足度も低下します。Power Platformの、すぐに作り、すぐに修正し、すぐに壊すことができるメリットを消してしまうことがないよう、メンバーの数は多すぎず、少なすぎず、かつ決定権のある人を含めることが重要となります。
また、コーディング標準を参考にしながらアプリ開発を進めていくと、今まで定義していなかったものの追記したい規約や、サンプルとして追加したいコードスニペットなどが出てくるかと思います。
これらをコーディング標準に反映させるタイミングは、多くても年に2回程度に抑えておいた方が良さそうだと感じています。
これは、Power Platform製品の、サービス側でのメジャーリリース（のアナウンス）が、原則として年に2回、4月と10月に行われることから、それらをコーディング標準へ反映する作業に合わせて自社特有の規約の追加・変更も行うと、改訂作業が一度で済むことが理由です。
さらに、コーディング標準の周知は、新卒入社のメンバーが部門に配属される時期（弊社の場合は、例年だと5月頃）に行われることが多いので、そのタイミングを目指して改訂すると無駄がないことも理由の1つです。
大まかな構成
コーディング標準の構成例として、弊社で作成しているコーディング標準から主要な見出しを抜粋してみます。
- 用語定義
- 開発工程
- 開発環境
- バージョニング
- 用語集
- 命名規約
- 画面デザイン（ UI / UX 観点）
- ロジック実装
それぞれの項目にどのような約束事を記載するべきか、ご説明していきます。
用語定義
コーディング標準の中で登場する用語について記載します。
例えば、2語以上の英単語から構成される複合語の記述方法の定義として命名規約で頻出する パスカルケース や ケバブケース といった呼称がありますが、こうした用語の共通理解が読み手にないと、それらの用語を使用した命名規約の内容や意図が伝わり難くなってしまいます。そのため、コーディング標準のなかで利用する用語の名称や使用例、使い分けの基準や意図などをまとめて定義しておきます。
用語は原則として、公式資料（ Microsoft Learn ）に従い、表記揺れが起きないようにします。また、自社に特有の用語（テナントやネットワーク環境、クライアントPCの種別によく現れます）があれば、併せて定義しておきます。
開発工程
自社の標準的な開発工程を提案フェーズから本番リリースまで列挙し、各工程の目的、その工程で実施する内容、作成する成果物、全体に対する比率の目安を定義しておきます。
まずはウォーターフォール開発手法の工程を定義しておき、実際にプロジェクトを進めるうえでアジャイル開発手法を採用する場合には、それをイテレーション内で実施するイメージとします。
開発工程を標準化しておくことで、スケジュールを立て（WBSを作成し）たり、想定コストの概算を算出したりする際の工数を削減しやすくなります。また、成果物についても、標準化してテンプレートを作成しておくことで、別のプロジェクトでも再利用し、コストを削減することができます。
各開発工程の定義や比率については、IPAによる「ソフトウェア開発データ白書」が参考になります。これをもとに、自社特有の事情も加味して定義していきます。
開発環境
アプリやフローを作成する際に使用する、PCやソフトウェアについて定義しておきます。弊社の場合は、全社員が使用するPCが共通化されているため、PCの差異によって問題が生じた例は多くありませんが、インストールされている（されていない）ソフトウェアによって開発効率が左右されることがあるため、トラブルシューティングの際の参考情報としての意味も含めて記載しておくと便利です。
Power Apps や Power Automate は基本的にブラウザから利用する Web アプリケーションのため、クライアントPCにインストールするソフトウェアはありませんが、開発を補助するツールとして、 XRMToolBox や Visual Studio Code といったアプリケーションのインストールを、また、形が似ている文字（ `0` と `O` 、 `1` と `l` ）の誤読を回避するためにデザインされた、 源ノ角ゴシック や PlemolJP といったフォントのインストールを推奨しておきます。
XRMToolBox や Visual Studio Code については、拡張機能をインストールすることで機能を拡張することができるアプリケーションなので、推奨する拡張機能についても定義しておきます。
バージョニング
ソフトウェア開発において、ソースコードのバージョンの管理が適切でないために不具合が生じることはよくあります。Power Platformにもバージョンを管理するための機能は用意されていますが、一般的に利用されている git などの バージョン管理ツール とは使い勝手が異なるため、バージョンを管理するための手順についても明示しておくことが望ましいです。
また、開発者が公開したアプリの最新バージョンと、利用者が実行しているアプリのバージョンが異なることによる不具合、データ不整合というのも、アプリを運用していく中ではよく発生する事象のため、トラブルシューティングの観点でも、すぐにバージョンを確認できる構成（UI / ロジック）にしておくことが重要となります。
ソリューションパッケージのバージョン番号を採番する際には、 セマンティックバージョニング を使用します。
セマンティックバージョニングとは、ピリオドで区切られた3つの数値の組合せで、バージョン番号を採番する方法です。
| <メジャーバージョン>.<マイナーバージョン>.<パッチバージョン（リビジョン）> |
以下の決まりに従って3つそれぞれの数値を定めていきます。
- メジャーバージョンが「0」の場合は、ベータ版や社内レビュー前であることを示す
- ドキュメントのバージョン採番では、作成開始時点で「0.1」、更新・レビューごとにマイナーバージョンアップ、顧客レビュー後にメジャーバージョンを「1」とすることが多い
- メジャーバージョンが「0」のままだと製品が未完成である印象を与えるので、社外に提示するものには「0」を使用しない
- メジャーバージョンが「1」の場合は、（一旦は）正式版として公開されたことを示す
- 変更が加えられたときにインクリメントする（バージョンを1増やす）条件
- 後方互換性を持たない変更を加えた場合には、メジャーバージョンを 1 増やす
- 後方互換性を保ちつつ機能追加した場合には、マイナーバージョンを 1 増やす
- 後方互換性を保ちつつバグ修正した場合には、パッチバージョンを 1 増やす
また、キャンバスアプリのバージョン番号を採番する際には、Power Appsの機能によらず、独自に 環境変数 や、アプリ内の 名前付き計算式 などに定義しておくと良いかと思います。
なぜかというと、Power Apps標準の機能としては、整数値によるバージョン番号が自動的に採番されるのですが、このバージョン番号は、実行しているキャンバスアプリの中から取得することができない（ appVersion として取得できる値が、バージョン 番号 ではなく、公開済みのバージョンが保存された 日時 ）という利用しにくい仕様となっており、アプリ内で 最新バージョン判定のロジック や、古いバージョンのアプリが実行されている場合に、ブラウザの再読み込みを要求するような機能を組み込む際に、結局バージョン番号を独自に定義する必要があるというのが理由です。
用語集
アプリやフローの変数名、Dataverseテーブルの表示名といった識別子には日本語などのマルチバイト文字列も利用できますが、Dataverseテーブルの論理名やSharePointリストの内部名といった箇所では利用できないため、英単語（句）で命名する必要があります。そのため、データモデルやアプリの実装において、よく利用される語句と訳語を、用語集としてまとめておくと便利です。
よく使われる語句
「社員」、「担当者」、「作成日」といった、データモデルを定義する際によく使用される語句と訳語を列挙します。
類義語
英和辞書の訳語としては同じような意味を持つ英単語でも、語の持つニュアンスが異なり、用途も異なる場合があるので、類義語一覧として掲載しておくことで、迷わず単語を使い分けられるようにします。
誤用されがちな語句
日本人が間違えやすい単語（ datum (単) ↔ data (複) 、 register (名詞) ↔ register (動詞) など）や、歴史的経緯から通常の英語とは用法や綴りが異なる単語（HTTPヘッダーのRefererなど）を一覧化し、誤用を防ぎます。
命名規約
Power Platform 環境、Dataverse テーブル、Power Apps キャンバスアプリ、モデル駆動型アプリ、Power Automate クラウドフローといった、 ソリューションコンポーネントの種類ごとに 、命名規約を定義します。
すべての規約をゼロから定義しようとするとかなり大変なので、 PowerApps Canvas App Coding Standards and Guidelines や、Microsoft Learnで公開されているベストプラクティスなどの公式資料を土台に、不足していたり、自社にマッチしていない箇所の代替策を示したりする形で定義するとスムーズです。
画面デザイン（ UI / UX 観点）
モデル駆動型アプリでは、テーブル構成に基づいてビューやフォームを作成するため、できあがるUIはある程度一貫性のある（制約のある）ものになります。一方で、キャンバスアプリでは、PowerPointでスライドを作るのと同様に自由度高くUIを作成できてしまうため、コーディング標準で画面設計にある程度 制約を持たせた方が、一貫性のあるUIとすることができます 。
画面設計の基本的な方針を検討する前に、 デジタル庁 から公開されている「 ウェブアクセシビリティ導入ガイドブック 」を読んでおくとイメージしやすくなるのでおすすめです。
コーディング標準自体は、開発者向けのものであり、開発効率を向上させることを主な目的として用意するものですが、そのコーディング標準を用いて作成されたアプリは、利用者向けのものであり、利用者の業務効率を向上させることを目的として作成するはずです。
ですので、特に画面デザインにおいては、まずは利用者が使いやすいデザインであるか、次に開発者が開発しやすいデザインであるか、という軸に基づいて規約を定めていくと、執筆者一人ひとりの慣れや嗜好の違いに左右されることなく、コーディング標準を作り上げていくことができます。
私たちがこれまでアプリを作成してきた経験をもとに、どのようなアプリでも共通して実装させた方が良いと考えている事柄を以下に挙げます。
手順書いらずのUI
プロジェクトの成果物として、アプリとは別に操作マニュアルを用意することが多いかと思いますが、残念ながら利用者に読まれることはほとんどありません。
アプリのUIとして、ヘルプアイコンを配置してマウスオーバー時に操作手順を表示したり、折りたたみ要素に操作手順を隠しておいて必要に応じて開いて確認したりできるように実装して、手順書を参照しなくてもスムーズに利用できるようにします。
オブジェクト指向UI
既存システムのリプレースのためにPower Appsの、特にモデル駆動型アプリを導入する場合に多いのですが、ひと昔前のWebシステムによく見られる タスク思考UI と、Power Appsで標準的な オブジェクト指向UI の差異から、移行直後に利用者が操作に迷ってしまうことがあります。
将来的にはオブジェクト指向UIによるアプリで統一されることが望ましいですが、利用者が慣れるまでの一時的な対処として、タスク思考でも操作できるアプリを用意する必要があるかもしれません（キャンバスアプリで独自実装する必要があります）。
バージョン情報表示
バージョニングの項でも挙げましたが、トラブルシューティングの際に、利用者が実行しているアプリのバージョンを速やかに確認したい状況はよく発生します。利用者自身がすぐに目で見て確認できる場所に、バージョン番号を表示しておくことを推奨します。
ロジック実装
アプリやロジックの実装は、UIとは異なり、利用者が直接見るものではありませんが、実行時間（パフォーマンス）やトラブル時の復旧時間といった形で利用者にも影響を及ぼすことがあります。
Dataverseへの CRUD処理 や、外部の REST APIの呼出し 、 ODataクエリ によるフィルタリング、ログ出力（特にログの出力タイミングや粒度）といった、頻出ロジックをサンプルとして列挙することで、類似のアプリを実装する際に再利用できるようにしておきます。
特に、プログラミング言語を利用したことのない市民開発者の場合、条件分岐や繰り返し処理といった 制御構文 を実装する際、処理のイメージがついていなかったり、 計算量のオーダー を考慮しない低パフォーマンスの数式を記述してしまったりすることがあるため、具体例を交えて定義しておくと有用です。
まとめ
今回は、実際に弊社で作成しているコーディング標準をもとに、どのような内容を定義し、記載すべきか、どのように運用・改訂していくのか、具体例を交えてご紹介しました。これからPower Platformを導入しようとしている組織や、既にPower Platformを導入していて今後より市民開発を広げたい組織において、コーディング標準を活用することで、業務改善に繋げていただければ幸いです。
弊社の Power Platform サポート＆アプリカタログサービス では、アプリの提供・開発だけではなく、今回ご紹介したようなガイドラインの策定や、市民開発者コミュニティの運営、ガバナンス管理に対するサポートも積極的に行っています。
市民開発を支える体制を構築したり、運用・監査マニュアル類を一から整備したりするのはなかなか困難ですので、本サービスをご活用いただき、迅速な立ち上げに繋げていただければと考えています。
まずはお気軽にお問い合わせください。
このブログで参照されている、Microsoft、Windows、その他のマイクロソフト製品およびサービスは、米国およびその他の国におけるマイクロソフトの商標または登録商標です。
