コーディング標準

コードがクリーンであるとは、チーム内の誰もが簡単に理解できることです。

クリーンコードは、元の作成者以外の開発者によっても読み取られ、改良することができます。理解しやすさにより、可読性、変更性、拡張性、保守性が得られます。

関連スキル

• csharp-14-dotnet-10-ai-kit
• csharp-12-dotnet-8-ai-kit

一般ルール

1. 標準的な規則に従う - 確立されたコーディング標準に一貫して従う
2. シンプルに保つ(KISS) - より単純な方が常に良い。複雑さをできるだけ減らす
3. ボーイスカウト・ルール - キャンプ場を見つけた時よりもきれいにして去る
4. 常に根本原因を見つける - 問題の根本原因を常に探す

設計ルール

1. 設定データは高レベルに配置する - 設定は容易にアクセスでき、変更可能である必要があります
2. if/else または switch/case よりポリモーフィズムを優先する - 拡張性のためにオブジェクト指向の原則を使用する
3. マルチスレッドコードを分離する - 並行コードを明確性と安全性のために隔離する
4. 過度な設定可能性を防ぐ - 目的なしにすべてを設定可能にしない
5. 依存性注入を使用する - 疎結合性とテスト可能性を有効にする
6. デメテルの法則に従う - クラスはその直接的な依存関係のみを知るべき

理解しやすさのヒント

1. 一貫性を保つ - ある方法で何かを行う場合、似たすべてのことを同じ方法で行う
2. 説明変数を使用する - 変数名を自己説明的にする
3. 境界条件をカプセル化する - 境界条件処理を1つの場所に配置する
4. プリミティブ型よりも専用の値オブジェクトを優先する - ドメイン固有の型を使用する
5. 論理的依存関係を避ける - 同じクラス内の他のものに依存するメソッドを記述しない
6. 否定的な条件文を避ける - 可読性のため肯定的な条件を優先する

命名ルール

1. 説明的で曖昧でない名前を選択する - 名前は意図を明確に表すべき
2. 意味のある区別を行う - 違いを明確にしない似た名前を避ける
3. 発音可能な名前を使用する - 名前は口頭で議論しやすくあるべき
4. 検索可能な名前を使用する - ループカウンタを除き、1文字の変数を避ける
5. マジックナンバーを名前付き定数に置き換える - 意味のある定数名を使用する
6. エンコーディングを避ける - 名前に接頭辞や型情報を付加しない

C# 固有の命名規則

• PascalCase: コンポーネント名、メソッド名、パブリックメンバー、クラス、インターフェース
• camelCase: プライベートフィールド、ローカル変数、メソッドパラメータ
• インターフェース接頭辞: インターフェースには "I" 接頭辞を使用 (例: IUserService)
• 定数: 定数には PascalCase を使用 (MaxRetryCount)
• プライベートフィールド: camelCase を使用、オプションでアンダースコア接頭辞 (_userName)

関数ルール

1. 小さくする - 関数は小さく、焦点を絞るべき
2. 1つのことを行う - 関数レベルでの単一責任原則
3. 説明的な名前を使用する - 関数名は意図を明確に説明するべき
4. 引数を少なくする - パラメータの数を最小限にする
5. 副作用がない - 関数には隠れた動作がないべき
6. フラグ引数を使用しない - メソッドを独立したメソッドに分割する

関数の例

// GOOD - 説明的な名前、単一の目的、少ない引数
public async Task<User> GetUserByIdAsync(int userId, CancellationToken cancellationToken)
{
    return await _userRepository.GetByIdAsync(userId, cancellationToken);
}

// BAD - 不明確な名前、フラグパラメータ
public async Task<User> ProcessUser(int userId, bool includeDetails, bool updateCache)
{
    // 複数の責任を持つ複雑なロジック
}

// BETTER - 焦点を絞ったメソッドに分割
public async Task<User> GetUserAsync(int userId, CancellationToken cancellationToken)
{
    return await _userRepository.GetByIdAsync(userId, cancellationToken);
}

public async Task<UserDetails> GetUserWithDetailsAsync(int userId, CancellationToken cancellationToken)
{
    return await _userRepository.GetWithDetailsAsync(userId, cancellationToken);
}

コメントルール

1. 常にコードで説明しようと試みる - コードは自己説明的であるべき
2. 冗長にならない - コードが既に述べていることを繰り返さない
3. 明らかなノイズを追加しない - 自明なコメントを避ける
4. 閉じ括弧のコメントを使用しない - 最新の IDE がこれを処理する
5. コードをコメント化しない - バージョン管理を使用し、単に不要なコードを削除する
6. 意図の説明として使用する - 何かではなく、なぜかを説明する
7. コードの明確化として使用する - 複雑なアルゴリズムやビジネスルールを明確にする
8. 結果についての警告として使用する - 潜在的な問題や副作用について警告する

コメントの例

// GOOD - ビジネス上の理由を説明
// 外部サービスが高負荷期間中に一時的なエラーを返すことがあるため、
// 最大3回までリトライします
var retryPolicy = Policy.Handle<HttpRequestException>()
    .WaitAndRetryAsync(3, retryAttempt => TimeSpan.FromSeconds(Math.Pow(2, retryAttempt)));

// BAD - 自明なことを述べている
// カウンタを1増加させる
counter++;

// GOOD - 結果についての警告
// 危険: このメソッドはユーザーデータを永久に削除し、取り消すことはできません
public async Task DeleteUserPermanentlyAsync(int userId)
{
    // 実装
}

ソースコード構造

1. 概念を垂直に分離する - 空白行を使用して異なるアイデアを分離する
2. 関連するコードは垂直方向に密集させる - 関連するコードを近くに配置する
3. 変数を使用位置の近くで宣言する - 変数スコープを最小化する
4. 依存する関数を近くに配置する - 呼び出された関数を呼び出し元の近くに配置する
5. 似た関数を近くに配置する - 関連する機能をグループ化する
6. 関数を下向きの方向に配置する - パブリックメソッドを上に、プライベートを下に
7. 行を短くする - 1行あたり 80〜120 文字を目指す
8. 水平方向の配置を使用しない - 割り当てや宣言の配置を避ける
9. 空白を使用して関連するものを関連付ける - 関連するステートメントをグループ化する
10. インデントを崩さない - 一貫したインデントレベルを維持する

オブジェクトとデータ構造

1. 内部構造を隠す - 実装の詳細をカプセル化する
2. 単純なデータにはデータ構造を優先する - クラスは動作用、構造体はデータ用
3. ハイブリッド構造を避ける - オブジェクトとデータ構造を混在させない
4. 小さくあるべき - クラスは焦点を絞った責任を持つべき
5. 1つのことを行う - 単一責任原則
6. 少数のインスタンス変数 - 状態の複雑さを最小化する
7. 変数は説明的な名前を持つべき - 略語や否定を含まない
8. 基底クラスは派生クラスについて何も知らないべき - 密結合を避ける
9. 条件付き動作よりも多くの関数がある方がよい - ポリモーフィズムを優先する
10. 静的メソッドよりも非静的メソッドを優先する - より良いテストと柔軟性を有効にする

クラス構造の例

// GOOD - 焦点を絞った責任、明確な構造
public class UserValidator
{
    private readonly IUserRepository _userRepository;
    private readonly ILogger<UserValidator> _logger;

    public UserValidator(IUserRepository userRepository, ILogger<UserValidator> logger)
    {
        _userRepository = userRepository ?? throw new ArgumentNullException(nameof(userRepository));
        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
    }

    public async Task<ValidationResult> ValidateAsync(User user, CancellationToken cancellationToken)
    {
        if (user == null) return ValidationResult.Invalid("User cannot be null");
        
        List<string> errors = [];
        
        if (string.IsNullOrWhiteSpace(user.Email))
            errors.Add("Email is required");
            
        if (await IsEmailTakenAsync(user.Email, cancellationToken))
            errors.Add("Email is already in use");
            
        return errors.Any() 
            ? ValidationResult.Invalid(errors) 
            : ValidationResult.Valid();
    }

    private async Task<bool> IsEmailTakenAsync(string email, CancellationToken cancellationToken)
    {
        var existingUser = await _userRepository.GetByEmailAsync(email, cancellationToken);
        return existingUser != null;
    }
}

テストガイドライン

1. テストごとに1つのアサーション - 各テストを単一の動作に焦点を当てる
2. 読みやすい - テストは理解しやすくあるべき
3. 高速 - テストは迅速に実行されるべき
4. 独立 - テストは互いに依存しないべき
5. 反復可能 - テストは一貫した結果を生み出すべき

テストの例

[Fact]
public async Task ValidateAsync_WhenUserIsNull_ShouldReturnInvalidResult()
{
    // Arrange
    var validator = new UserValidator(_mockRepository.Object, _mockLogger.Object);

    // Act
    var result = await validator.ValidateAsync(null, CancellationToken.None);

    // Assert
    result.IsValid.Should().BeFalse();
    result.Errors.Should().Contain("User cannot be null");
}

避けるべきコード臭

1. 硬直性 - ソフトウェアが変更困難で、小さな変更が連鎖的な変更を引き起こす
2. 脆弱性 - 単一の変更により、複数の場所でソフトウェアが破損する
3. 不可動性 - 高い労力とリスクのため、他のプロジェクトでコードの一部を再利用できない
4. 不要な複雑性 - ソリューションのオーバーエンジニアリング
5. 不要な繰り返し - 抽象化なしのコード重複
6. 不透明性 - コードが理解しにくく、意図が不明確である

Microsoft ガイドライン

公式の Microsoft C# コーディング規則に従う: C# Coding Conventions

関連標準

• ロギング標準 - ロギングのベストプラクティス
• SOLID原則 - オブジェクト指向設計原則

外部リファレンス

• Clean Code Summary
• Microsoft C# Style Guide

基になったドキュメント

https://netwealth.atlassian.net/wiki/spaces/BS/pages/52628480/Coding+Standards