見慣れないコードを読む
1行ずつ訳すのではなく、データの流れで説明する
次のコードを説明してください。条件：1）まず全体として何をしているかを一文で；2）次にデータの流れに沿って、入力がどこから来て、どんな変換を経て、出力がどこへ行くかを述べる；3）最も読み間違えやすい箇所を2〜3つ示す；4）不要に見える箇所、怪しい箇所を指摘する。文法を1行ずつ訳さないこと。 ``` ［コードを貼り付けてください］ ```
使い方
すでに理解している関数についての説明と突き合わせましょう。そこが違っていれば、残りも信用できません。
向いている場面
- 他人のモジュールを引き継いだとき、またはドキュメントのない OSS ライブラリの入口ファイルを読むとき。
- コードを変更したいが副作用の境界が分からず、まずデータの流れの地図がほしいとき。
向いていない場面
- コードがスキャフォールド生成の設定ファイルなら、公式ドキュメントを読むほうが速いです。
- ある関数のシグネチャだけ知りたいなら、型定義を見るか grep で呼び出し元を探します。
例
入力
def settle(order, now=None):
now = now or datetime.utcnow()
if order.status != "paid" or order.settled_at:
return None
amt = order.amount - sum(r.amount for r in order.refunds)
ledger.post(order.id, amt, at=now)
order.settled_at = now
return amt得られるもの
まず一文で「支払済みで未精算の注文について、返金を差し引いた純額を ledger に記帳する処理」と述べます。次に status の判定、純額の計算、ledger.post の副作用、settled_at の書き込みという流れで説明し、`return None` が「精算すべきでない」と「精算済み」の両方を意味する点、post の後に settled_at を書くため原子的でない点を、読み違えやすい箇所として示します。
よくある誤用
- 2000 行のファイル全体を貼って説明を求めると、出力はセクションごとの要約に退化し、データの流れがファイルの境界で切れます。
- 関数本体だけを貼り、ledger.post のシグネチャや order モデルを渡さないと、副作用を誤って推測します。説明はもっともらしいのに使えません。
こう変えると効く
- 「精算金額に関わる部分だけ」と加えると、これから変更する経路に説明が集中します。
- 「呼び出し順に並べ、各段階で失敗しうる箇所に印を付けて」と頼むと、説明ではなく障害点の地図が返ってきます。