菜单
コードを書く・レビューする・リファクタするときに適用する、可読性重視の コーディング規約。自明なコメントの排除と「目的(why)」コメント、ガード節による 早期リターン(正常系を浅いインデントへ)、意味のある命名(tmp/buf など汎用名の禁止)、 複雑なワンライナーの回避を扱う。Go / Python / Rust / TypeScript など言語を問わず適用する。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | readable-code |
| description | コードを書く・レビューする・リファクタするときに適用する、可読性重視の コーディング規約。自明なコメントの排除と「目的(why)」コメント、ガード節による 早期リターン(正常系を浅いインデントへ)、意味のある命名(tmp/buf など汎用名の禁止)、 複雑なワンライナーの回避を扱う。Go / Python / Rust / TypeScript など言語を問わず適用する。 |
コードの「意図」を最短で読み取れる状態を優先するための規約。 書くとき・レビューするとき・リファクタするときに、以下の原則を適用・指摘する。
これらは特定の流儀ではなく、広く知られた設計原則 (Fowler の Refactoring、McConnell の Code Complete、Clean Code、Cognitive Complexity) に沿ったもの。末尾の参考に一次情報を挙げる。
コードを読めば分かることをコメントで繰り返さない。実装を更新したときにコメントの更新が 漏れると、コードとコメントが矛盾し、無いより有害になる (stale comment)。
インラインコメントを書きたくなったら、それは次のどちらかのサイン:
// Bad: コードそのままの説明。実装が変われば即座に嘘になる
// i を 1 増やす
i++
// x が 0 より大きいかチェック
if x > 0 {
// ユーザーに手数料を加算する
total = total + x*rate
}
// Good: コメントを消し、名前と抽出で意図を語らせる
i++
if hasPositiveBalance(x) {
total = addTransactionFee(total, x, rate)
}
コメントを消すこと自体が目的ではない。「コメントで補う」代わりに 「名前と構造で自明にする」ことが目的。
コメントを残すなら、その処理が何をしているか (what) ではなく、 なぜそうするのか / 何を目的としているのか (why) を書く。 関数レベルのドキュメントで、処理の目的・背景・制約・トレードオフを説明する。
whatはコードが語る。whyはコードに書けない — だからコメントの出番はそこだけ。
# Bad: 何をしているかの逐語訳 (コードを読めば分かる)
# retries が 3 未満の間ループする
while retries < 3:
...
# Good: なぜ 3 なのか / 何のためか (コードからは読めない)
# 決済APIは瞬断が多い。恒久障害と切り分けるため最大3回だけ再試行する。
MAX_PAYMENT_RETRIES = 3
while retries < MAX_PAYMENT_RETRIES:
...
残す価値があるコメントの例:
エラーケース・前提を満たさないケースは、関数の入口で早期リターンして閉じる。
ループ内なら continue で早期に打ち切る。異常系を先に処理しきると、以降は
「正常系だけを考えればよい」状態になり、読み手の負荷が下がる。
// Bad: 正常系が if の内側に潜り、ネストが深くなる
func process(order *Order) error {
if order != nil {
if order.Paid {
if len(order.Items) > 0 {
return ship(order)
} else {
return errors.New("no items")
}
} else {
return errors.New("not paid")
}
} else {
return errors.New("nil order")
}
}
// Good: 異常系をガード節で先に閉じる
func process(order *Order) error {
if order == nil {
return errors.New("nil order")
}
if !order.Paid {
return errors.New("not paid")
}
if len(order.Items) == 0 {
return errors.New("no items")
}
return ship(order)
}
ループでも同じ:
# Good: 対象外を continue で早期に弾き、本処理はネストの外
for user in users:
if user.is_disabled:
continue
if not user.email:
continue
send_newsletter(user)
原則3の帰結。if status == "OK" の then 側で本処理をしない。
代わりに if status != "OK" で早期リターンし、本当に行いたい処理を
関数スコープの浅い位置に集約する。読みたいコードの意図が一番浅い所に並ぶ。
// Bad: 本命の処理が then 側の奥にある
if status == "OK" {
result := doTheRealWork()
save(result)
notify(result)
}
return
// Good: 異常系で抜け、本命は関数の地の文に並ぶ
if status != "OK" {
return
}
result := doTheRealWork()
save(result)
notify(result)
分岐が「異常系 vs 正常系」ではなく、同格の複数ケースの振り分け (いわゆる switch 相当) の場合は、無理に早期リターンへ潰さない。 むしろ意図が「多方向分岐」であることが伝わる形にする。
# 同格の分岐は無理にガード節化しない。可能なら switch/match で意図を明示
match kind:
case "circle":
return circle_area(r)
case "square":
return square_area(r)
case "triangle":
return triangle_area(r)
case _:
raise ValueError(f"unknown kind: {kind}")
1行に詰め込んだ賢いコードは、書くのは一度・読むのは何度も、という非対称のコスト。 三項演算子の入れ子、長すぎるメソッドチェーン、副作用を織り込んだ内包表記などは、 適切な変数名を挟んで段階に分ける。行数は増えても認知負荷は下がる (cognitive complexity の低減)。
// Bad: 何を判定したいのか一読で分からない
const r = u && u.roles && u.roles.find(x => x.a && x.lvl > (u.vip ? 2 : 5)) ? "y" : "n";
// Good: 中間結果に名前を付け、判断を段階に分ける
const requiredLevel = user?.vip ? 2 : 5;
const hasQualifyingRole = (user?.roles ?? [])
.some(role => role.active && role.level > requiredLevel);
const result = hasQualifyingRole ? "y" : "n";
短さ (code golf) は目的ではない。目的は「意図が最短で伝わること」。
tmp temp buf data val flag x のような汎用名は、その変数が
何であるかを隠す。名前と構造に意味を持たせる。McConnell の
「1変数=1用途」原則に従い、使い回しもしない。
// Bad: 何が入っているか名前から分からない
tmp := getUser(id)
buf := tmp.Orders
data := 0
for _, x := range buf {
data += x.Price
}
// Good: 役割がそのまま名前になっている
user := getUser(id)
orders := user.Orders
totalPrice := 0
for _, order := range orders {
totalPrice += order.Price
}
i, j)、
数学的慣習 (x, y 座標) など、意味が自明な場合のみコードを書き終えたら / レビューするときに、この観点で見直す:
tmp / buf / data などの汎用名は、役割を表す名前に変えたか (原則6)theUserWhoJustLoggedInToTheSystem の
ように冗長化しない。スコープが狭いほど短くてよい。