# コーディングガイドライン DAPEにおけるコーディングガイドラインを定めます。 ## 原則 ### 日本語を用いる DAPE のコアメンバーは日本語ネイティブのため、各種コミュニケーション・記述にあたっては日本語を用いることとします。 ### Microsoft が推奨するコーディングガイドラインをベースとして用いる [Microsoft が推奨するコーディングガイドライン (英語)](https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/coding-style/coding-conventions) 及び [命名ガイドライン (英語)](https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/coding-style/identifier-names) をベースとして用います。 ### 車輪の再発明をしない我々は暇ではないため、車輪の再発明をするべきではありません。例えば、非中央集権的なマイクロサービス群において、事実上重複しない識別子をマイクロサービス間でコミュニケーションすることなく採番したい場合を考えます。この時、目的に合致する UUIDv4 などの世の中ですでに広く受け入れられているアプローチを取るべきです。また、すでに存在するライブラリの使用を検討することなく DAPE で実装することもあってはなりません。使用を検討し、ライセンスや目的が合致しない場合、かつフォークや修正も不可能な場合に限って DAPE で実装することを検討してください。さらに、すでに標準ライブラリに存在する場合はサードパーティーに存在するライブラリよりも優先して使用します。 ### ドキュメントよりも命名、命名よりもシグネチャメソッドやプロパティ、フィールドなどに書かれるドキュメントは往々にしてコードベースとの同期が遅れ、腐りやすいです。そのため、ドキュメントに書く前に命名に反映できないか検討してください。また、命名に反映する前に、戻り値型、引数の型、属性によって表現できないか検討してください。以下は、検討にあたって優先するべき順位で並べた指針です。 1. 引数の型・戻り値の型 2. 属性 3. 命名 4. コードと同じファイルに埋め込まれるドキュメント 5. コードと異なるファイルに置かれるドキュメント ## Git ### master に直pushしない master に直接pushするのは以下の理由で大変危険です。 1. CI・CDの結果が後手になる 2. バグがあった場合、壊れた状態をベースにすることになる ### feature branch を作成する上の話と関係しますが、新規機能追加・バグ修正・リファクタリングなどあらゆる変更を積むためにはまず feature branch を作成してください。 (※便宜的に *feature branch* と名前をつけていますが、 *feature* 以外でも *feature branch* を作成してください。その際、ブランチの名前に以下の名前をつけないでください。 * `master` * `main` * `trunk` * `develop` * `live` * `gh-pages` ### コミットの粒度バグの bisect が簡単になるように、ローカルのブランチでは細かい単位でコミットすることを推奨します。また、後述の Conventional Commits におけるプレフィクスが混合しない粒度に切り分けてください。 ### コミットメッセージ 1. 何をしたか後で見返してわかるようなメッセージにしましょう。 2. [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) を採用します。 ### Conventional Commits のプレフィクス DAPE のコミットメッセージでは、一貫性のためにプレフィクスへ以下の定義を与えることにします。 * `build`: ビルド構成を追加・変更したとき・ライブラリのバージョンを変えたとき・ライブラリを導入したとき * `chore`: 雑用 * `ci`: 継続的インテグレーション * `docs`: ドキュメンテーション * `feat`: 機能追加 * `fix`: バグ修正 * `perf`: パフォーマンス改善 * `refactor`: リファクタリング * `style`: コードのスタイルを修正したとき * `test`: テストを追加・変更・削除したとき参考: https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#type TODO: Renovate の挙動を揃える ## GitHub ### Pull Request を作成するこれも上の話と関係しますが、常に Pull Requst を作成してください。 ### CI が通っていない Pull Request をマージしない DAPE では品質担保の手段として継続的インテグレーション (CI) を採用しています。 CI が通っていないということは、システムのトラブルを除けばその変更が何らかの理由で受け入れ不可能ということです。問題点を修正する前に CI が通っていない Pull Request をマージしないようにしてください。 ## 命名 ### C# の予約語と同じ識別子は避ける C# の予約語と同じ識別子は避けてください。raw identifier escape を用いても同様です。理由: `@` がタイピングしにくいため。 ### 非同期メソッドの名前には `Async` を後置する `Task` または `Task` を返すメソッドには、末尾に `Async` を付けてください。例外: 明確に非同期であると分かる文脈（例: `IAsyncOperation.Execute()`）では `Async` を省略してもかまいません。理由: メソッドの使用箇所から非同期性が一目で分かるようにするためです。 ### `static` フィールド・プロパティの名前に `s_` を前置しない `static` なフィールド・プロパティの名前に `s_` を前置しないでください。参考: CA1716 ### System.Attribute のサブクラスの名前に `Attribute` を後置しない C# の属性クラスは、言語仕様上、使用時に末尾の `Attribute` を省略できます。例えば、 ```cs [Serializable] public class SerializableAttribute : Attribute { } ``` と書けば、`[Serializable]` とだけ記述して使えます。そのため、DAPE のコードベースでは属性クラス名の末尾に Attribute を付ける冗長な命名は避け、より簡潔な名前を推奨します。ただし、他のフレームワークやライブラリと名前が衝突しないよう注意してください。 ### スコープの長さに応じて説明度が高い名前をつけるスコープが広いほど、変数やメソッドなどの名前はより説明的で意味が明確なものにしてください。逆に、スコープが極めて限定的（例: for ループ内など）であれば、簡潔な名前を使用してもかまいません。スコープが広くなると、名前の参照場所と定義場所が離れるため、短い・曖昧な名前では意味が把握しづらくなります。レキシカルスコープに限らず、以下のような観点から潜在的なスコープの長さを推定し、名前の説明度を調整してください。 | 属性 | スコープが長くなる傾向の方向 | |:-----------|:-------------------------------------------------| | アクセス修飾子 | `private` < `protected` < `internal` < `public` | | `readonly` | ない方がスコープが長い（状態変化が起き得る） | | `static` | ある方がスコープが長い（インスタンスに依存しないため共有範囲が広い） | | `sealed` | ない方がスコープが長い（継承先で使われる可能性がある） | | `virtual` | ある方がスコープが長い（オーバーライドされ得るため多様な場所で使用されうる） | | `abstract` | ある方がスコープが長い（継承先クラスで実装する必要がある） | | `const` | ない方がスコープが長い（再代入が起き得る） | 命名例: | スコープ | 命名例 | 解説 | |:-------------------|:-------------------------------------------------------|:----------------------------------| | ローカル変数（for文内） | `i`, `result` | 数行以内で完結する用途なら簡潔に | | メソッド内で再利用されるローカル変数 | `userName`, `isRetryEnabled` | 意味を明確に | | private フィールド | `_lastLoginTime` | クラス全体で使われるため説明的に | | public プロパティ・クラス名 | `UserDisplayName`, `IsAdministrator`, `OrderProcessor` | 外部に公開されるインターフェースや型として、読みやすく明確な名前に | ※ `i` は許容されうるが、必要に応じてもっと説明的な名前をつけること。悪い例: ```cs private int _x; // 何の数値か分からない ``` 良い例: ```cs private int _retryCount; ``` 備考: この指針は変数・フィールド・プロパティ・メソッド・クラス名などすべてに適用されます。**「外に見せるものほど自己説明的であるべき」 ** という原則を忘れないでください。 ### ペアになるものはペアになるような名前をつけるペアになる識別子はペアと認識できるような名前をつけてください。例: 1. `first` と `second` 2. `dest` と `src` 3. `prev` と `next` 4. `x` と `y`、`a` と `b` * スコープが狭い場合に限る 5. `lhs` と `rhs` ### `temp` や `tmp` を使わない * 一時的であること: `temporary` をつける * 温度: `temparture` をつける * テンプレート: `template` をつける * 値を破棄する: `_` に代入する * スワップ代入する: `(a, b) = (b, a)` パターンを使う * `a`, `b` は適宜名前を変えること ### `Utility` またはそれに類する名前をクラス名に入れない以下の部分文字列は、*神クラス* を招きやすいため、クラス名の一部として利用しないでください。 * `Utility` * `Util` ### 否定形のプロパティ命名について * IsDisabled のような否定形の命名は、一般的に可読性が落ちるため避け、前向きな命名（例: IsEnabled）を推奨します。 * ただし、肯定形プロパティのみの場合、両方用意すると冗長になるため否定形を追加しないことは許容します。 * 否定形プロパティが存在しない場合でも、if (!x) のような否定条件は特別に許容し、読みやすさを優先します。 ## 命名以外の構文的な規則 ### `var` はどこでも使う我々は統合開発環境を用いてコーディングをするため、`var` が使える箇所ではどこでも `var` を使用します。 ### `private` フィールド・プロパティ以外で型名を省略したコンストラクタの呼び出しを行わない型名を省略したコンストラクタの呼び出しを行わないでください。違反例: ```cs Meter meter = new(); ``` 修正例: ```cs var meter = new Meter(); ``` 例外: `private` フィールド及びプロパティを除きます。 ```cs public class Foo { private Meter _meter = new(); } ``` ### cypherクエリとして解釈されることを意図している定数文字列にはコメントをつける JetBrains Rider を使用し、推奨プラグインを読み込んでいる場合、コードベースでハイライトが効くようになります。例: ```csharp // language=cypher const string CREATE_USER = "CREATE (:Person{name:\"Taro\", age:20});" ``` ## 意味論的な規則 ### ユーザー定義演算子は常識的な振る舞いをさせるユーザー定義演算子を定義するときは、「常識的」かつ「行儀が良い」な振る舞いをさせるようにしましょう。以下は、判断の基準を示したケースです: #### 算術シフト・論理シフト以外の振る舞いを見せるシフト演算子を定義しない C++ の iostream の過ちを、我々は二度と繰り返すべきではありません。参考: #### 加減算は、原則として同じ単位量に基づく型のインスタンスの間でのみ行うメートル同士の足し算は良いが、メートルとセンチメートルを足したときに結果がどうなるか議論の余地があるため、一旦禁止する。 #### 乗除算の結果の型は、次元ベクトルの和として自然に合成された複合単位を返す例えば、キログラムにメートル毎秒毎秒を乗算した時、その結果を表す型の指数ベクトルは `{ mass: 1, length: 1, second: -2 }` でなければならない。 \ 参考: これはニュートンの定義に当たる。 #### 乗算の右オペランドにプリミティブを使用する場合、その意味論はスカラー倍にする `Meter.operator*(int) -> Meter` （スカラー倍で意味が明確） #### 除算の左オペランドと右オペランドが同じ次元ベクトルの単位の場合、その戻り値は比率にする `Meter.operator/(Meter) -> double` （比率計算で意味が明確） #### 複数通りの解釈を生むユーザー定義演算子を避ける `TimeSpan.operator+(int) -> TimeSpan` のように、演算子のシグネチャや名前から動作の意図が明確にわからないユーザー定義演算子は定義しないでください。推奨される代替手段 1. 明示的なメソッドを定義し、動作が一目でわかる名前を付ける。例: `TimeSpan.AddMinutes(int) -> TimeSpan` 2. 引数の型を具体化し、意味を明確にする。例: `TimeSpan.operator+(Minute) -> TimeSpan` ### 等価性とハッシュコードは一貫した振る舞いを見せる値型や参照型で等価性を定義する場合、==演算子、`Equals` メソッド、 `GetHashCode` メソッドの意味論を必ず一致させます。`record`/`record struct`は自動的にこれを満たすため積極的に利用してください。参照型で意味的等価性を定義する場合、参照同一性と混同しないよう注意します。 ### 型変換関数は禁止 `implicit` / `explicit` 演算子はアップキャストと字面上で区別がつかないため禁止します。インターフェースを用いるか、明示的なメソッドを用いるようにしてください。 ### リスコフの置換原則を破らないリスコフの置換原則を破ることを禁止します。 ### is-a 関係が成立する場合のみ継承を使う is-a 関係が成立する場合のみ継承を使用してください。 ### has-a 関係で継承を用いない has-a 関係が成立するときに継承を用いないでください。代わりに、"composition over inheritance" 原則に従ってフィールドなどで has-a 関係を表現するようにしてください。 ### 外部からの値について検証なしに仮定を置かない外部からの値については、全く信頼できないものです。常に性悪説を採用し、想定外・不正・欠損・過不足が生じるものとして明示的な検証を行います。勝手な仮定を置かないようにしてください。これにはデータベースから null が返ってこないこと、HTTP リクエストが特定の形式に従っていること、外部サービスからの取得結果が特定の規則に従っていることなどがありますが、それに限りません。 ### リソース管理を伴うクラスは必ず破棄できるようにするリソース管理を伴うクラスはIDisposableまたはIAsyncDisposableを必ず実装し、Dispose()/DisposeAsync()後のメソッド呼び出しではObjectDisposedExceptionをスローします。Dispose/DisposeAsyncを複数回呼び出しても例外を投げない実装を推奨しますが、Dispose済みインスタンスの再利用は必ず例外で検出できるようにしてください。 ### 非同期メソッドのキャンセル設計非同期メソッド（async）には可能な限りCancellationTokenパラメータを追加し、呼び出し側がキャンセル制御できるようにしてください。メソッド内でtoken.ThrowIfCancellationRequested()を適切なタイミングで呼び出し、キャンセル要求を速やかに反映します。CancellationTokenのデフォルト値はdefaultでよいですが、意図がある場合はドキュメントで説明します。 ### 準正常系ケースに例外を使用しない例外を使用するのは異常系のケースに限定します。 ### `partial` の使用はコード生成および責務分離に限定する `partial` キーワードを使用してクラスや構造体を定義する場合は、以下のような目的に限定してください。 - 自動生成されたコードと手書きコードの分離（例: `*.g.cs` ファイル） - 単一クラスに複数の責務（ビューとロジックなど）を明示的に分割する場合上記以外の理由による `partial` の使用は避けてください。 ### 匿名型およびタプルの使用はスコープを限定し、要素名を説明的にする匿名型 (`new { ... }`) や `ValueTuple` (`(int x, int y)`) を使用する場合は、以下を守ってください。 - 使うスコープを限定的（メソッド内）にとどめる - 要素名は必ず意味のあるものにする - メソッドの戻り値やフィールドとしては使用しない（型情報が失われるため）悪い例: ```cs return (1, 2); ``` 良い例: ```cs return (rowCount: 1, columnCount: 2); ``` ### 独自の例外型には `Exception` を末尾に付け、スロー条件を明確にする独自の例外型を定義する場合は、`System.Exception` またはそのサブクラスを継承し、型名の末尾に `Exception` を付けてください。 - `InvalidConfigurationException` - `DataAccessException` また、例外をスローする際には、その条件をドキュメントまたはコードコメントで明示してください。 ```cs /// Throws when the user is not found in the database. throw new UserNotFoundException(userId); ``` 例外を返すのではなく、投げる（throw）ことを前提としてください。 ### nullable reference types をすべてのアセンブリで使うすべてのアセンブリで nullable reference types を有効とし、nullable reference types に対応したコードのみを記述してください。アセンブリ全体で NRT を有効にするためには、その `.csproj` に次のように記述します。 ```xml enable ``` * `string?` など、 `null` 許容型を意図的に使う場合は、`null` になるケース、及びその時の値の取り扱いについてコメントで明記してください。 * `#nullable disable` は使用禁止とします。 * `null` である可能性を排除したい場合は、明示的な `null` チェックによって `null` かどうかをチェックするようにしてください。 * 明示的な `null` チェックを入れることなく `null` である可能性を排除したい場合、`!` 演算子によって排除してください。 ### 値オブジェクトはできるだけ `record struct` にする `record struct` を用いると、スタック上に乗るようになり、かつコンパイラーが自動的に挿入する防御的クローンもなくなるためメリットが大きいです。 ### `readonly` を使うイミュータブルなオブジェクトを厳密に実現するのは不可能ですが、再代入を禁止することはできます。その一歩が `readonly` です。 ### 必要なとき以外セッターを生やさないセッターはイミュータブル性にとって最大の敵です。必要な時を除き、セッターを生やさないようにしましょう。 ## コレクション ### `Memory` よりも `Span` 後者は `stackalloc` 演算子のターゲットにもなります。 ### `Memory` よりも `ReadOnlyMemory` 要素の書き換えが必要ないならば、 `ReadOnly` がついたほうを採用してください。 `Span` も同様です。 ### `T[]` よりも `List` 要素数が固定である場合を除いて、 `List` を使うようにしましょう。 ### `List` よりも `IEnumerable` 反復するだけ・LINQを使いたいだけなら `IEnumerable` にしましょう。 ## 外部入力 ### 許容できない外部入力は早期に例外を投げる許容できない外部入力は、なるべく早い段階で例外（ArgumentException, FormatException, InvalidOperationException等）をスローし、バグや攻撃の連鎖を防いでください。 ### ログと監査証跡外部入力によるエラー・例外発生時は、最低限エラー内容と入力値の概要をログに記録し、監査・トラブルシュートできるようにしてください。ただし個人情報等の扱いには十分注意を払ってください。 ### 外部入力を表示するときはフレームワークが提供する機構でエスケープする外部入力をWeb画面やXML等に出力する際は、XSS/XXE/CSRFなどのセキュリティリスクを考慮し、フレームワーク標準のエスケープ・検証機構を使ってください。 ### cypherクエリを文字列結合で組み立てないこと Cypherクエリを文字列結合で組み立てることを禁止します。理由: SQL インジェクションと同じ原理で、 Cypher-Injection になります。改善方法: [java.sql.PreparedStatement](https://docs.oracle.com/javase/jp/8/docs/api/java/sql/PreparedStatement.html) よろしく、パラメーターバインディング構文が用意されているのでそれを使うようにしましょう。例: ```csharp await using var session = driver.AsyncSession(sess => sess.WithDefaultAccessMode(AccessMode.Write)); await session.ExecuteWriteAsync(tx => { // language=cypher var query = "CREATE (n:Person { handle: $name, id: $id })"; var parameters = new { name = user.GetPreferredHandle(), id = user.GetIdentifier().Raw.ToString() }; return tx.RunAsync(query); }); ``` Note: 匿名型の使用は上記のセクションでクラスメソッドの外にでない場合は許可されています。 ## LINQ ### クエリ式を使わないクエリ式を禁止します。理由: 一貫性に欠けるため。修正方法: `IEnumerable`・`IQueryable` などのメソッドチェーンを使う。 ### ラムダの中で参照透過性を損なう操作を起こさない LINQメソッドチェーンに与えるラムダの中で、副作用を起こす操作を禁止します。理由: デバッグするのが大変になるため。修正方法: 参照透過性を損なう操作をラムダ式から追い出す。 ### メソッドチェーンは1回につき1行使う 1行に押し込められていると横に伸びてしまうため、LINQメソッド1回の呼び出しにつき1行を使用してください。 ### ToList や ToArray などの集約関数を不必要に呼び出さない `ToList` や `ToArray` はソースをすべて消費して、 `List` や `T[]` を生成します。また、無限に生成されるソースに対して呼び出したり、メモリ消費が激しい型に対して呼び出すとメモリ枯渇によるサービス拒否に繋がります。そのため、それらの値全体が厳密にほしい時を除いて、不必要に呼び出さないでください。修正方法: 単に反復したいだけなら `foreach` 文に渡してください。 ## ドキュメンテーション ### xml docs は必要なとき以外書かない XML Docs. は腐りやすいです。原則「ドキュメントよりも命名、命名よりもシグネチャ」に反するため、挙動を特に説明したいとき以外は原則書かないようにしてください。「挙動を特に説明したいとき」とは、シグネチャでも命名でも説明できない文脈や事項を注記し、その内容をツールチップで表示したいときを指します。 ### コードと異なるファイルに置かれるドキュメントには、高次のドキュメントのみ置くコードと異なるファイルに置かれるドキュメントについては、高次のドキュメントのみ置くようにしてください。「高次のドキュメント」とは、以下のような個々のファイルをまたぐ大きいスコープに対するドキュメントです。 * ARCHITECTURE.md (DAPE の設計の解説) * CODING_GUIDELINE.md (DAPE のコードを統制するガイドライン) * CONTRIBUTING.md (DAPE に貢献する方法の紹介) * FAQ.md (DAPE のよくある質問) * LICENSE.md (DAPE の利用が許可される範囲) * README.md (DAPE の紹介、インストール方法、……) ## 機密情報 ### トークンをハードコードしない各種サービスの認証情報はコード上に直接埋め込まないようにしましょう。代わりに、`.env` や `config.json` などファイルパスを環境変数やコマンドラインスイッチから指定する方法を使用します。 ### コマンドライン引数や環境変数から認証情報を直接与えないコマンドライン引数や環境変数から認証情報を与えるような設計を行わないようにしてください。 Linuxではどちらもprocfsから読み取り可能なため、隠れていると思っていても実際には隠れていません。 ## テスト ### どのように振る舞うことが期待されているのかテスト名で明確にするどのように振る舞うことが期待されているのかテスト名で明確にしてください。一覧で表示したときに視認性が向上します。 ### Arrange-Act-Assert パターンを採用するテストコードには Arrange-Act-Assert パターンを採用し、初期化→アクション→結果の確認という基本形に従ってください。参考: ## 用語の定義 ### "Shared Kernel" という用語は用いない "Shared Kernel" という単語は意味が不明瞭なため、排除します。代わりに、すべてのモジュールに共通する基礎として *Base レイヤー* という単語を用います。