📄

バックエンド開発ドキュメント(C# .NET webAPI)

2025/02/02に公開

はじめに

C# .NETを使用したバックエンド開発(webAPI)の知見がたまってきたためコード規約をまとめてみた。

開発環境

以下の開発環境を参考に(自身が作成した開発環境テンプレート)話を進めていく。
フォルダ構造等の情報は、READMEに記載。
https://github.com/MachinoTakumi52/WebAPIWithDotNet

共通

基本ルール

命名規則

  • 原則開発言語のルールに準ずる
    だれでも開発しやすいように使用する言語の命名規則にしたがって開発していく。

  • 品詞を意識
    日本語を入れることは原則禁止し、品詞を意識しながら開発する。
    省略した言葉は使用せず不要な単語は入れない。
    ただ、不要な単語を入れないように意識しすぎて可読性が下がることがないようにする。
    それにより多少名前が長くなることは問題ない。

  • 配列,リスト名
    〇〇Listのようにするのではなく〇〇sとする。

  • CRUD の名前
    関数などを作成する際に、人によって登録や更新などの言葉が違うため
    CRUD 関係の関数やクラスを定義する際に必ずつけるプレフィクスを以下に定義する。

    CRUD 名 プレフィックス
    登録 Create
    取得 Read
    更新 Update
    削除 Delete
  • 定数は、アッパーキャメルで統一
    公式でも記述されているようにアッパーキャメルで定義する。
    昔は、大文字のスネークケースだったが、IDE やエディタの発達により見分けがつきやすくなったためだと思うので、公式に準じて定義する。

開発ドキュメント[C#]

定数定義

  • 原則Constを使用
    定数の書き方として、conststatic readOnlyの2つが存在する。
    それぞれ振る舞いが違うし、const のバージョニングという問題があり
    状況によって変わってくる。
    そのため、本当に不変かつプリミティブな値しか定数化しないかつ同プロジェクト内で定数を管理するのであれば、constで統一する。
    プロジェクトが大きくなり、共通関数やライブラリを別プロジェクトで管理する時は、static readOnlyで統一する。

変数定義

  • 基本は、明示的に型を定義する
    基本、明示的に型を定義してあげる。
    公式のコーディング規約によるとコンストラクタ呼び出し時は、右辺は明示的になっているため、var を使用するのが一般的らしいが、それを考慮すると、人によって差異が生まれてしまう可能性があるため、明示的に型を適宜してあげることで統一する。
    イレギュラーとして、匿名型はvarを使用して宣言する(そうしないと匿名型は宣言できないため)。

  • new 演算子の利用は可
    コンストラクタの呼び出しの一つであるnew演算子の利用は可とする。
    明示的に型を宣言するため、new演算子を利用しても可読性は、低下しないし省略できるため良い。

  • 文字列結合はテンプレートリテラルを使用
    可読性が上がるため。

    // NG
    public string Sample(string text)
    {
      return "hello " + text;
    }
    
    // OK
    public string Sample(string text)
    {
      return $"hello {text}";
    }
    

関数定義

  • 関数の呼び出し
    可読性の向上のため、関数の呼び出しは以下のようにして行う。
// 関数宣言
public void Function(string a, string b)
{
    Console.WriteLine($"a: {a}, b: {b}");
}

// 関数呼び出し
// 引数のパラメーター名を明示する
Function(a: "sample1", b: "sample2");

比較演算

  • 論理否定演算子を使用しない
    !を許容すると、いろいろな書き方がソース上で存在する可能性がある。
    その場合、可読性がおちてしまうため、書き方を統一する。

    // NG
    if (!isExists) {
    }
    
    // OK
    if (isExists == false) {
    }
    

オプショナルチェイニング

  • 仕様を理解した上で使う
    オプショナルチェイニングは、短絡評価を行うため、後続の呼び出しがスキップされる。
    そのことを踏まえた上で使用しないと意図しないエラーを起こす可能性がある。
    また、本来は必ず値があるべきという場所で ?. を使うと、エラーを握りつぶしてしまうため、エラーが発見しづらくなる。
    オプショナルチェイニングは「このプロパティ(またはメソッド)が本当になくてもいい(あったら使うが、なくてもエラーにしない)」という認識のもと意識しながら使用してほしい。

Null 合体演算子,論理代入演算子

  • 原則使用しない
    論理代入演算子や null 合体演算子の仕様を把握していないとオプショナルチェイニングと同じで、変数やプロパティが意図せず書き換えられる可能性がある。
    また、他の演算子と合わせると(例: x ||= y ??= z;)みにくく、if 文などで書いた方が良い。
    慣れている人ならば良いが、あまり見慣れていない人からすると誤った使用をしたり可読性が低下するので原則使用しない。

非 null アサーション演算子

  • むやみやたらに使用しない
    null でないことを確認して使用する。

    string? value = null;
    
    if (value != null) {
      console.log(value!.toUpperCase());
    }
    
GitHubで編集を提案

Discussion