reflect

リフレクト

最初の実装はドラフトです。コードができたので、最善の方法で実装できているか、見直して再検討してください。コードとその背景について問いかけてください。製品上の判断に左右されない改善は実施し、それ以外は報告してください。

目標は、ユーザーが詳細に確認する前に、初回の実装をより高品質に仕上げることです。これはコードレビューではありません。正式なレビューは後で行います。

「最善」とは、次のことを意味します。

• 問題を解決する、最もシンプルな解決策である
• ドメインモデルが明確に表現されている
• 既存のコードベースと一貫性があり、調和している
• 適切な場合は、既存のオブジェクト、ヘルパー、規約を再利用している
• 新しい要件を想定して作られていない既存コードに無理に合わせていない
• コメントでコードの意図と理由を説明している
• コードベース全体の品質を高め、ほかの人が参考にできる例を示している
• 変更を最小限にするのではなく、長期的に適切なアーキテクチャを採用している

使用するタイミング

• ユーザーが「リフレクト」「もう一度見直す」「セカンドパス」「形を整える」と言ったとき
• 最初の実装を終えた後。WIPへの段階的な変更を終えた後も含みます
• 計画中や設計上の質問への回答待ちの間、または正式なレビューの代わりとしては使用しないでください

ワークフロー

1. コードを見る

変更内容を初めて見るように読み直してください。新規・変更ファイルと、それらが組み込まれる周辺モジュールを確認します。目標は、差分を最小にすることではなく、高品質な最終形にすることです。

2. 問題を探して対処する

以下の問いに取り組んでください。製品上の判断に左右されない気づきは、すべて実行してください。今書いたコードの改善について許可を求めないでください。

以下の場合は変更せず、報告に残してください。

• 要件を緩和、変更、または削除する必要がある
• 製品として妥当な方法が2つあり、どちらがよいか明らかでない
• ビルド中に製品上の判断が暗黙に行われた
• 既存コードの大幅なリファクタリングが必要である

3. 繰り返す

反復するたびに、新たな問題や改善の機会が見つかります。安定するまで、またはユーザーの入力が必要な製品・設計上の判断だけが残るまで、振り返りと改善のプロセスを繰り返してください。

4. 報告する

簡潔に報告してください。変更内容を伝えた後、残っている指摘と判断事項を番号付きで示します。

ユーザーの返答を待ってください。

問い

基本的には、自分の判断で進めてください。

コードを確認できるようになった今、これはニーズに応える最もシンプルで最善の方法でしょうか。もっとシンプルに、または分かりやすくできるでしょうか。

今書いたものについて、以下を問いかけてください。

• どの要件が複雑さを生んでいますか。要件を厳格に解釈しすぎていませんか。暗黙の要件は何ですか。それらについてユーザーに問いかけてください。
• コードが見えた今、より一貫性のある形に並べ替えられますか。
• 簡素化や改善の機会は生まれていますか。
• 中核となる概念は、一度だけ、再利用できる形で表現されていますか。
• 不自然な点や意外な点はありませんか。なぜそうなっていますか。
• 新しいコードは、コードベースの欠点を回避していませんか。もっと直接的な修正方法はありますか。
• どのような結合が生まれ、または明らかになりましたか。それは妥当ですか。
• このコードはここに置くべきですか。それとも、必要とされる場所の近くに置くべきですか。
• 受け渡して利用箇所の近くに置くべきものを、取り消したり、内部を調べたりしていませんか。
• 類似する処理や構造をうまく統合できますか。
• 同じことをする方法が2つありませんか。どちらかに統一してください。
• コードの各部分は適切な場所にありますか。
• これは本当に必要ですか。何か役割を果たしていますか。
• 本当に任意であるべきものはどれですか。
• コードのにおいはありますか。
• 名前は現在の概念を適切に表していますか。
• この問題全体にとって、適切なアーキテクチャは何ですか。
• 最初から始めるとしても、本当にこのように実装しますか。
• これはハックではありませんか。

暗黙の製品判断

コードに問題がなくても、以下は報告してください。ユーザーから確認を得ていないためです。

• ユーザーに見える2つの振る舞いのうち、どちらかを選んだ
• アプリケーションのルールをコードに組み込んだ
• ゲート、上限、空の状態、またはコピー経路を独自に設けた
• ユーザーが見直したい可能性のあるデフォルト値を選んだ

してはいけないこと

• 要件を黙って削除したり、緩和したりする
• 基底クラスや、将来想定される2つ目の呼び出し元をでっち上げる
• すでに導入された API フィールドの名前を変更する
• 回避策を残す
• これをレビュー差分やコミットのゲートとして扱う