ベストプラクティス

本プロジェクトで使用されている慣例、および純粋に優れた実践のリストです。これらは厳格な規則ではなく、コードベースの大部分がこれらの基準を満たしているわけではありません。

命名規則

良い名前とは:

  • 短縮しない:意味が不明瞭になる場合は短縮しません。 例: countは良いが cntは良くない。
  • 文脈から明白: direction::leftは明確です。一方、int rotate はドキュメントを読む必要があります。
  • 周囲の命名規則に従う:
    • max_stored_kcal と stored_kcalのように、近くの変数名と同じ慣例に従います。
    • max_stored_calories と stored_kcal のような混在を避ける代わりに、stored_kcal または caloried_stored のように一貫させます。

プロジェクトの大部分のコードとの一貫性を保つため、snake_case が推奨されます。

クラス

  • 名前空間内の通常の関数で機能する場合、メソッドを追加しない:
    • 誤った例:Character.consume_tools(tool_list)
    • 推奨例:crafting::consume_tools(tool_list,Character &)(名前空間内の関数)
  • フィールドの読み書きしか行わない場合、ゲッターとセッターの両方を追加しない: これらは単なる隠されたフィールドであるためです。
    • パブリックなセッターがないゲッターは許可されます。
  • アクセス指定子:
    1. 可能な限りprivate を使用します。
    2. 1 のケースが不可能な場合にpublic を使用します。
    3. 明確な理由がある場合にのみ protected を使用します。

型の定義

  • ポインタを避ける:代わりに、参照、std::optional または可能な場合は関数オーバーロードを使用します。
  • ヘッダー内での std::pair および std::tuple の使用を避ける: 代わりに、名前付きの構造体を作成します。
  • enum class が機能する場合、int や std::string の使用を避ける。

ファイル編成

他のヘッダーからヘッダーをインクルードすることは、できる限り避けてください。これはコンパイル時間（クリーンビルドと部分ビルドの両方）に悪影響を及ぼし、特に問題のヘッダーが既に大きい (例: character.h、avatar.h、map.h、game.h、item.h、npc.hなど)か、広く使用されている場合に顕著です。また、ソースファイルに、知る必要のない定義が不用意に含まれることになります。

ここではいくつかのヒントがあります:

  • 前方宣言を使用する: コンパイラは、常にクラスの完全な定義を知る必要はありません。前方宣言で十分な場合があります。

    • 例えば、character.h で vehicle クラスが 型の関数引数としてのみ使用されている場合、参照は参照する型に関係なく常に同じサイズであるため、コンパイラは vehicle & という名前の型が存在することだけを知っていればよく、その内部の詳細は必要ありません。
    • この場合、character.h に class vehicle の宣言を追加するだけで十分です。

  • Pimpl イディオムを使用する クラスメンバの定義の必要性を排除するために、pointer-to-implementation イディオムを使用することが可能です。

    • 実装と説明についてはsrc/pimpl.h を参照してください。コードベースには多くの使用例がありますが(主に game.h)、全体的な考え方は、クラスメンバーをポインタに置き換え、ポインタを介してメンバにアクセスするときにのみ定義を要求するというものです。
    • これにはわずかなパフォーマンスオーバーヘッドが発生しますが、ほとんどの場合は無視できる程度です。

  • 専用ヘッダーを作成する: 頻繁にインクルードされるヘッダーに何らかの機能を追加していて、その機能が少数のソースファイルでのみ使用されることになっている場合、個別のヘッダーを作成することを検討してください。

    • これにより、あなたのコードはそれを一切使用しない数十または数百のコンパイルユニットに取り込まれることがなくなり、コンパイラは不要なビルドに時間を費やさなくなります。

  • システムヘッダーと標準ヘッダーのインクルードは許可: それらのほとんどはプリコンパイルされているため、問題ありません。

  • 一般的な「ユーティリティ」ヘッダーのインクルードは許可:(例:optional.h、 calendar.h、 coordinates.hなど) これらはすでに多くのヘッダーやソースファイルで広範囲に使用されているため、これらをインクルードしないことによる影響は、不便さを正当化するには小さすぎます。