冗長さを避ける

名前と型シグネチャは多くの情報を伝えるため、それをコメントで繰り返さないでください。

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

// 名前/型の情報を繰り返している。省略できる！
/// str から ipv4 を解析する。失敗モードには option を返す。
fn parse_ip_addr_v4(input: &str) -> Option<IpAddrV4> { ... }

// フィールド名から明らかな情報を繰り返している。省略できる！
struct BusinessAsset {
    /// 顧客 id。
    customer_id: u64,
}

// 最初に型名に言及している。こうしないこと！
/// `ServerSynchronizer` はローカルの編集を送信するオーケストレーターである [...]
struct ServerSynchronizer { ... }

// より良い！目的に焦点を当てている。
/// ローカルの編集を送信する [...]
struct ServerSynchronizer { ... }

// 最初に関数名に言及している。こうしないこと！
/// `sync_to_server` はローカルの編集を送信する [...]
fn sync_to_server(...)

// より良い！関数に焦点を当てている。
/// ローカルの編集を送信する [...]
fn sync_to_server(...)

  • 動機: 名前/シグネチャの情報を単に繰り返すだけのドキュメントは、API 利用者に何も新しい情報を提供しません。

    さらに、シグネチャの情報は時間とともに変わる可能性がありますが、それに合わせてドキュメントが更新されるとは限りません。

  • これは陥りやすいパターンです！

    「常にコードをドキュメント化せよ」という助言に対する素朴なアプローチでは、この助言を文字どおりに受け取ってしまい、その意図には従えていません。

    一部のツールはドキュメントの網羅率を強制することがありますが、この種のドキュメントは手軽な対処になりがちです。

  • ドキュメントの異なるモードの目的を意識してください。

    • ライブラリコードは、それが何のために使われるのか、その範囲や、それを使おうとしている人々の幅広さを理解した形でドキュメント化する必要があります。

    • アプリケーションコードは目的がより限定的であるため、もっと単純で直接的でも問題ありません。

  • アイテムの名前は、そのアイテムのドキュメントの一部です。

    同様に、関数のシグネチャはその関数のドキュメントの一部です。

    したがって、doc comment の記述を始める時点で、アイテムのいくつかの側面はすでにカバーされています。

    項目を並べること自体を目的に、情報を繰り返さないでください。

  • 標準ライブラリの多くの領域でドキュメントが最小限なのは、名前と型だけで十分な情報が得られるからです。

    経験則: 利用者の視点から見て、何の情報が不足しているでしょうか。名前、シグネチャ、実装の無関係な詳細以外で考えてください。

  • Rust や標準ライブラリの基本事項を説明しないでください。読者は言語そのものについて中級程度の理解を持っていると想定してください。自分の API のドキュメント化に集中してください。

    たとえば、関数が Result を返す場合、Result や疑問符演算子がどのように動作するかを説明する必要はありません。

さらに詳しく

  • #![warn(missing_docs)] lint は、doc comment の存在を強制するのに役立つことがありますが、開発者に大きな負担を課し、その結果としてこのような質の低いコメントを書くパターンに寄りかかる原因になり得ます。

    この種の lint は、プロジェクトの保守担当者がその要求に継続して対応できる場合にのみ有効にすべきであり、通常はアプリケーションコードではなくライブラリスタイルの crate に対してのみ有効にすべきです。