coding

コーディング

目標

実行方法、データの流れ、正しく動作し続けていることを証明する根拠に照らして、その形が妥当なコードを書きます。

抽象的なアーキテクチャの好みよりも、直接的で測定可能な根拠を優先します。2つの設計で迷ったら、実行時の動作、メモリトラフィック、割り当て回数、分岐の形、データ局所性、生成コード、検証コストがどう変わるかを考えます。

デフォルトのワークフロー

1. ローカルのルールを読みます。編集する前に、リポジトリの指示と関連するソースを確認します。
2. 実際の経路を見つけます。リクエストによって変更されるコードパス、読み書きされるデータ、動作を検証する境界を特定します。
3. 意図を持って再利用します。新しいものを追加する前に、既存の型、ヘルパー、フォルダー、検証コマンドを探します。
4. 性能面で最もシンプルな形を選びます。ロジックには関数、状態にはシンプルなデータオブジェクトを使い、入力と出力を明示し、ホットデータをコンパクトに保つレイアウトを選びます。
5. 計測の足場を整えます。性能が重要な作業や構造的な作業では、関連するコストを測定できる計測機能を作成するか、既存のものを使います。計測なしで作業するのは、盲目的に進めるのと同じです。
6. 文脈が失われる箇所にコメントを書きます。ホットパス、メモリレイアウト、計測の境界、直感に反するトレードオフを平易な言葉で説明します。
7. 検証します。変更を証明できる、対象を絞ったテスト、型チェック、ベンチマーク、トレース、検証コマンドを実行します。
8. 根拠を要約します。変更した動作、該当する場合は性能上の境界、検証コマンド、残るリスクを報告します。

性能を根拠とする設計

• 性能が重要になる可能性がある場合は、性能をスタイルの指針にします。オブジェクト、抽象化、フォルダー、間接参照を使うのは、そのコストに見合うだけの実行時性能、メモリトラフィック、局所性、検証しやすさ、読みやすさの向上がある場合に限ります。
• 関数の長さ、ファイル数、オブジェクト数といった恣意的なルールを、品質の根拠にしないでください。コードを分割するのは、データフロー、所有権、計測、局所性、検証が改善される場合です。
• 抽象化を追加する前に、それによって何が節約されるかを明らかにします。繰り返しの処理、コピーされるバイト数、割り当て、分岐、散在する読み取り、コンパイル時の重複、テストの複雑さなどです。
• 抽象化を取り除く前に、何がより低コスト、または明快になるかを明らかにします。呼び出しの減少、状態の削減、生成コードの単純化、データの集約、検証対象の縮小などです。
• 性能が重要なコードでは、必要に応じて実際のターゲットを調べます。ベンチマーク結果、トレース結果、アロケーターのカウント、メモリレイアウト、コンパイラー出力、逆アセンブリ、ハードウェアカウンターなどです。
• デフォルトでは、計算資源が限られた環境向けに最適化します。コンパクトなデータ、少ないメモリトラフィック、予測しやすいループ、最小限の割り当て、不要な製品レイヤーへの依存なしを心がけます。

状態とロジック

• ロジックには関数、状態にはシンプルなデータオブジェクトを優先します。
• オブジェクトやクラスは、主に一貫性のあるデータとシンプルなライフサイクルルールを保持するものにします。制御フロー、割り当て、性能コストを隠す複雑な変更メソッドは避けます。
• 状態を明示します。ストア、ワークスペース、コンテキスト、バッファーは、グローバルな可変状態の背後に隠さず、直接渡します。
• 実際のドメイン概念やデータレイアウトの概念には名前付きの型を使います。検証や意味づけが呼び出し箇所に分散する場合は、生の文字列、辞書、整数フラグを渡さないでください。
• 新たに先頭がアンダースコアの変数名を導入しないでください。値の内容を明確に示す名前を使います。値を本当に無視する場合に限り、その言語の破棄パターンを使います。この方針はヘルパー関数、ファイル、モジュールにも適用します。ただし、外部 API、生成コード、または変更対象領域ですでに使われている慣例が必要とする場合は除きます。
• オブジェクトを多用する設計を追加する場合は、局所性と明快さが向上するのか、それともポインターをたどる処理、隠れた変更、割り当て、テストの難しさが増すのかを確認します。

フォルダー構成

• 実行時の目的、データの所有権、検証方法、または変更頻度が共通するコードは、同じフォルダーにまとめてください。
• 実際の境界に沿ってフォルダーを分けてください。入力／読み込み、準備、計算、出力／レポート作成、検証、ベンチマーク、計測などです。
• 計算コードには、CLI の解析、ファイル I/O、レポートの組み立て、互換性アダプター、プロファイラー／エクスポートのロジックを含めないでください。
• ベンチマーク、検証、トレース、スクラッチ用のツールは、製品コードが限定的な計測ファサードを公開する場合を除き、製品のコードパスの外に置いてください。
• 複数のファイルが同じデータ形式を扱う場合は、雑多なユーティリティ用フォルダーにまとめるのではなく、目的を絞った小さなフォルダーを優先してください。

スキャフォールディングと計測

スキャフォールディングとは、パフォーマンス、正確性、データ形式の把握に役立つ、一時的なコードや境界内に限定されたコードです。複雑な実装作業では、これを用意するよう努めてください。適切な計測なしに作業するのは、状況が見えないまま作業するのと同じです。

境界が重要です。成熟した本番コードに、誰からも求められていない恒久的なスキャフォールディングを混入させてはいけません。その場合は、まずベンチマーク、トレース、カウンター、またはハーネスを、スクラッチ領域（/tmp、Git で無視されるローカルディレクトリなど、破棄可能な場所）にそのまま作成してください。インポートしたり、通常のビルドに組み込んだり、ユーザーに公開したり、コミットしたりしてはいけません。計測を残す価値がある場合は、コンパイル時に無効化できるようにするか、明示的なオプトインのビルドパスの背後に置いてください。計測や保持するベンチマーク資産をリポジトリに移す前に、ユーザーに確認してください。

• マイクロベンチマークでは、単一の関数、ループ、パーサーの処理経路、アロケーターのパターン、またはデータ配置の選択を測定します。
• エンドツーエンドベンチマークでは、セットアップや出力処理を含む、実際のユーザー向けまたは本番の境界を測定します。
• トレースゾーンとタイムラインプロファイリングでは、フェーズの構成、ネスト、重なり、停止箇所、時間の使われ方を確認できます。コストの内訳を説明するものであり、計測されていないランタイムではありません。
• 低オーバーヘッドのタイミングでは、観測コストを最小限に抑えて経過時間を測定します。変更前後の速度の主張にはこれを使用してください。
• ハードウェアカウンターでは、データ配置や分岐の振る舞いが問題となる場合に、サイクル数、命令数、キャッシュミス、分岐ミス、メモリ停止を測定します。
• アロケーションカウンターやアロケーターラッパーでは、アロケーション数、サイズ、ピーク時の生存バイト数、アロケーションの頻度、ホットループ内での意図しないアロケーションを測定します。
• メモリ配置レポートでは、構造体のサイズ、パディング、キャッシュラインの占有範囲、保持されるヒープサイズ、スタック使用量、コピーされたバイト数を測定します。
• コンパイラー出力や逆アセンブルの確認では、コンパイラーが期待どおりにロード、ストア、呼び出し、分岐、除算、ベクトル化、インライン化を行ったか確認できます。
• ゴールデン出力による検証では、最適化したコードが引き続き同じ観測可能な動作をすることを証明します。
• スクラッチハーネスを使えば、成熟した製品コードを変更せずに、問題を素早く切り分けられます。ユーザーが計測の保持を希望しない限り、破棄可能な状態にしてください。

計測に関するルール：

• 製品コードでは、小さなファサードを通じて限定的なシグナルを出力できます。
• 製品コードは、トレースファイル、レポート形式、プロファイラーの設定、シェルスクリプト、ダッシュボードを認識してはいけません。
• 計測を設定モジュール、スケジューラー、状態マネージャー、または別の実装経路にしてはいけません。
• 保持する計測は、コンパイル時に除外するか、デフォルトで何もしないようにするか、明示的なベンチマーク／トレース用ビルドでのみ有効にしてください。
• 成熟したコードベースでは、まずスクラッチ領域での計測を優先してください。計測のコミットは、要求された場合、またはユーザーが保持する証拠として残すことに同意した場合に限ります。
• 保持する証拠は、リポジトリ内の検証またはベンチマーク用領域に置いてください。スクラッチ用のトレースや調査結果は、破棄可能な状態に保ってください。
• 調査結果をコード、テスト、コメント、または保持する証拠に反映したら、スキャフォールディングを削除してください。

コメント

• コードだけでは読者が把握できない背景を伝える場合に、コメントを追加します。
• ホットパス、メモリレイアウト、計測の境界、直感的でないトレードオフについては、簡潔で構造化されたコメントを優先します。
• 次に読む人の状況を考慮します。パフォーマンス調査、うまくいかなかった代替案、ベンチマークの経緯を知っていると決めつけないでください。
• 平易な言葉を使います。コードベースですでに使われている用語を除き、専門用語は避けてください。使う場合は、「読み込むバイト数を減らす」「項目ごとの割り当てを避ける」「まれなデータをループの外に置く」など、具体的な効果と結び付けてください。
• 優れた構造化コメントでは、通常、次のいずれか一つ以上に答えます。Why:、Tradeoff:、Evidence:、Boundary:。
• 構文を説明したり、名前を言い換えたりしないでください。役立つコメント一つのほうが、巧妙でも曖昧なコメントをいくつも並べるより有効です。
• ユーザーが明示的に削除を求めない限り、Feedback: など、ユーザーが書いたメモは保持します。

ハードカットオーバーのルール

• フォールバックを優先する実装はしません。デフォルトではハードカットオーバーを使用します。
• ユーザーの明示的な承認に加え、担当者、削除日、追跡用の Issue、検証計画がない限り、互換性シム、二重経路、二重読み書き、レガシーフォールバックは追加しません。
• 古い動作にひそかにフォールバックする広範な catch ブロックは使用しません。
• 新旧のフィールド名を混在させ、暗黙のデフォルト値を使う or／|| の連鎖は使用しません。
• 古い動作を置き換える場合、安全であれば、同じ一貫した変更の中で古い経路を削除します。

アンチパターン

• 好み、パターン名、一般的な「クリーンコード」の主張だけを根拠に、パフォーマンスに関わる選択を正当化すること。
• オブジェクトがロジック、変更、割り当て、低速な経路を隠すオブジェクト指向の設計。
• 一つの実行時概念を抽象レイヤーに分散させるフォルダー分割。
• 計測が製品の動作に漏れ出したり、第二のアーキテクチャになったりすること。
• 無視できないパフォーマンス変更や構造変更で計測を避け、コードの形だけから推測すること。
• 残すべきかを確認せず、成熟したコードベースに足場コードをコミットすること。
• 境界、ウォームアップ状態、ワーカー数、検証条件が異なるベンチマークを比較すること。
• ホットパスで読み取り、分岐、再計算が増えるメモリ使用量の削減。
• 古い名前や経路を保つためだけに呼び出しを転送する互換性ラッパー。
• プライバシー、一時的な状態、「内部」コードを示すために、新しい先頭アンダースコア付きの名前を使うこと。代わりに、明確な名前を選んでください。
• 現時点で計測に基づく必要がない、推測に基づくパラメーター、フック、設定、抽象化。
• プロセス境界、FFI 境界、または真のシングルトンの外にあるグローバルな可変状態。
• 不明瞭な判断を専門用語で覆い隠すコメント。

レビューチェックリスト

• どの経路が変更され、動作はどこで検証されていますか？
• 重要なループやワークフローは、どのデータを読み書きしますか？
• 選んだ構成は、実行時間、メモリトラフィック、割り当て、分岐コスト、検証コストのいずれかを削減しますか？
• 外部インターフェイスや生成インターフェイスで必要な場合を除き、新しい先頭アンダースコア付きの名前を避けましたか？
• オブジェクト／クラスを追加した場合、隠れたロジックの入れ物ではなく、単純な状態保持オブジェクトになっていますか？
• フォルダー構造は、実際のデータ／実行時の所有関係ごとにコードをまとめていますか？
• 推測するのではなく、関連する足場コードや計測を活用しましたか？
• 計測は製品レイヤーの外にあるか、狭いファサード一つの背後にありますか？
• 成熟したコードベースの場合、残す足場コードをコミットする前に、一時的な計測を使用しましたか？
• ベンチマークと検証の境界は明示され、比較可能ですか？
• コメントは簡潔で、構造化され、平易な言葉で書かれており、背景を知らない読者にも役立ちますか？
• フォールバック優先の互換性用足場コードを避けましたか？
• 古くなった足場コード、使われていない経路、推測に基づくフックを削除しましたか？