Skip to content

docs: コードコメントを平易な技術英語に書き直す - #41

Merged
JunNishimura merged 18 commits into
mainfrom
docs/plain-english-comments
Nov 14, 2026
Merged

JunNishimura merged 18 commits into
mainfrom
docs/plain-english-comments

Conversation

@JunNishimura

Copy link
Copy Markdown
Owner

概要

コードコメントの英文を、一読で意味が取れる文体に書き直した。コードとテストケース名は変更していない。

これまでのコメントは文法的には正しいが、次の理由で読みにくかった。

  • 関係節が何段も入れ子になっている
  • 技術用語の代わりに日常語の言い回しを使っている(filed under、gives back、goes down など)
  • 主語が倒置されている(What was opened before a failure is closed again)
  • 1 文に条件・帰結・理由が詰め込まれている

変更は次の 3 つ。

  • CLAUDE.md の Comments に Style を追加し、書き方のルールを 5 つ定めた
  • 全 16 パッケージのコメントをそのルールで書き直した(テストファイル内のコメントを含む)
  • CLAUDE.md 自身の説明文も同じルールで書き直した
// Before
// BTreeIndex is an index that keeps its entries in order of the value they are
// filed under, in the leaves of a tree whose directory says which leaf a value
// is in.

// After
// BTreeIndex is an index that stores its entries in leaf blocks, sorted by
// key. A directory tree maps each key to the leaf that holds it.

レビューの進め方

差分は 181 ファイル、約 5,000 行と大きいが、コミットはパッケージごとに分けてある。

  • 全 .go ファイルについて、コメント行を除いた main との差分が空であることを機械的に確認した。コードの変更を探す必要はない。
  • 確認してほしいのは、コメントの意味が変わっていないかどうか。特に設計判断の理由を説明している長いコメントは、言い換えの幅が大きい。次の 3 つは元の文が込み入っていた。
    • metadata_manager/indexinfo.go の IndexInfo(トランザクションを保持する理由)
    • query/constant.go の Constant(型を保持する理由と == の説明)
    • plan/tableplanner.go の makeProductPlan(SimpleDB との違い)

設計上の判断

  • 用語を統一した。 インデックスの値は key、リーフのレコードは entry、ディレクトリのレコードは directory entry とした。ほかに gives back は unpins / returns、is refused は is rejected、the scan underneath は the underlying scan、a guess at は an estimate of に揃えた。
  • 元から平易なコメントは変更していない。 recovery_manager や短いアクセサの説明などが該当する。.golangci.yml と ci.yml のコメントも同じ理由で変更していない。
  • CLAUDE.md 内のテストケース名の例は変更していない。 実際のテスト名と対応しているため。

既知の制限

  • エラーメッセージ文字列に filed under が 3 か所残っている(index/btreeleaf.go、index/btreepage.go、index/hashindex.go)。コメントではなくコードなので、この PR では変更していない。
  • テストケース名は元の文体のまま。 変更するとテスト出力が変わるので、この PR の対象から外した。
  • go test ./...、gofmt、go vet は手元で通っている。golangci-lint は手元に入っていないため実行していない。-race と -shuffle=on 付きのテストも手元では実行していない。

🤖 Generated with Claude Code

JunNishimura and others added 18 commits November 15, 2026 00:32
既存のコメントは文法的には正しいが、関係節の入れ子や日常語への
言い換えが多く、一読で意味を取りにくい。全面的に書き直す前に、
書き直しの基準となるルールを定める。

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
CLAUDE.md の Comments > Style に合わせて index パッケージのコメントを
書き直した。用語は key / entry / directory entry / unpin に統一。
コードとテストケース名は変更していない。

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
CLAUDE.md の Comments > Style に合わせてコメントを書き直した。
コードとテストケース名は変更していない。

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
CLAUDE.md の Comments > Style に合わせてコメントを書き直した。
コードとテストケース名は変更していない。

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
CLAUDE.md の Comments > Style に合わせてコメントを書き直した。
コードとテストケース名は変更していない。

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
CLAUDE.md の Comments > Style に合わせてコメントを書き直した。
コードとテストケース名は変更していない。

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
CLAUDE.md の Comments > Style に合わせてコメントを書き直した。
コードとテストケース名は変更していない。

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
CLAUDE.md の Comments > Style に合わせてコメントを書き直した。
コードとテストケース名は変更していない。

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
CLAUDE.md の Comments > Style に合わせてコメントを書き直した。
コードとテストケース名は変更していない。

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
CLAUDE.md の Comments > Style に合わせてコメントを書き直した。
コードとテストケース名は変更していない。

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
CLAUDE.md の Comments > Style に合わせてコメントを書き直した。
コードとテストケース名は変更していない。

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
CLAUDE.md の Comments > Style に合わせてコメントを書き直した。
コードとテストケース名は変更していない。

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
CLAUDE.md の Comments > Style に合わせてコメントを書き直した。
コードとテストケース名は変更していない。

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
CLAUDE.md の Comments > Style に合わせてコメントを書き直した。
コードとテストケース名は変更していない。

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
CLAUDE.md の Comments > Style に合わせてコメントを書き直した。
コードとテストケース名は変更していない。

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
CLAUDE.md の Comments > Style に合わせてコメントを書き直した。
コードとテストケース名は変更していない。

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
CLAUDE.md の Comments > Style に合わせてコメントを書き直した。
コードとテストケース名は変更していない。

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Comments > Style のルールを CLAUDE.md 自身の説明文にも適用した。
テストケース名の例は実際のテスト名と対応しているため変更していない。

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@JunNishimura
JunNishimura merged commit 87fb6ae into main Nov 14, 2026
2 checks passed
@JunNishimura
JunNishimura deleted the docs/plain-english-comments branch November 14, 2026 16:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant