誰に向けて書いていますか？

同僚、協力者、普段はほとんど声を上げない API ユーザー、それとも自分自身ですか？

// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0

// 専門家は専門家に向けて書く
/// 借用チェッカーのために MIR を正準化します。  
///  
/// このパスは、MIR から LLVM-IR への変換に進む前に、  
/// すべての借用が NLL-Polonius の制約に適合することを保証します。  
pub fn canonicalize_mir(mir: &mut Mir) {
    // ...
}

// 専門家は初学者に向けて書く
/// 借用チェックに向けて中間レベル IR（MIR）を準備します。  
///  
/// 借用チェッカーは、単純化された「正準」形式の MIR を対象に動作します。  
/// この関数はその変換を行います。これは、コード生成の  
/// 最終段階に進むための前提条件です。  
///  
/// Rust の中間表現について詳しくは、  
/// [rustc-dev-guide](https://rustc-dev-guide.rust-lang.org/mir/index.html) を参照してください。  
pub fn canonicalize_mir(mir: &mut Mir) {
    // ...
}

  • 背景: 知識の呪い とは、 専門家が他者も自分と同じレベルの専門知識と視点を持っていると 想定してしまう認知バイアスです。

  • 動機: 読者は、あなたと同じレベルの専門知識や同じ 視点を持っているわけではありません。自分のような人に向けて書くのではなく、 他者に向けて書いてください。

  • 意図せず自分に向けて書いてしまうと、伝えたい要点や 説明したい概念が相手に理解されない原因になります。

  • ドキュメントを読んでいく中で実用的な情報を見つけられずに苦労している、 自分自身の過去の姿や、これまでに見てきた誰かを思い浮かべてください。

    コードベースのどの領域に doc comment の手当てが必要かを考えるときは、そうした人物像を念頭に置いてください。

  • 誰に向けて書いていますか？

  • 回りくどく長大な doc comment の中から重要な詳細を見つけられずに 苦労している、自分自身の過去の姿や、これまでに見てきた誰かも思い浮かべてください。 情報を詰め込みすぎないでください。

  • 常に問いかけてください: このドキュメントは API ユーザーにとって 理解の妨げになっていないか。必要なことを素早く把握できるか、 あるいは必要な情報がどこにあるかを見つけられるか。

  • 常に考慮してください: API レベルのドキュメントは専門家も読みます。doc comment は 読者にその分野の基礎を教えるのに適した場所ではないかもしれません。その場合は、 参照先を示し、名前を挙げてください。詳しい長文のドキュメントへ誘導しましょう。