「How」と「Where」ではなく、「Why」と「What」

頻繁に変わりうる無関係な詳細をドキュメント化するのは避けてください。

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

// 悪い例
/// `User` レコードを Postgres データベースに保存します。  
///  
/// この関数は新しい接続を開いてトランザクションを開始します。指定された  
/// ID を持つユーザーが存在するかを `SELECT` クエリで確認します。ユーザーが  
/// 見つからない場合は、`INSERT` を実行します。  
///  
/// # エラー  
///  
/// いずれかのデータベース操作が失敗した場合は、エラーを返します。  
pub fn save_user(user: &User) -> Result<(), db::Error> {
    // ...
}

// 良い例
/// ユーザーレコードをアトミックに保存します。  
///  
/// # エラー  
///  
/// ユーザー（キーは `user.username` フィールド）がすでに存在する場合は、  
/// `db::Error::DuplicateUsername` エラーを返します。  
pub fn save_user(user: &User) -> Result<(), db::Error> {
    // ...
}

動機: ユーザーが知りたいのは、実装の詳細ではなく API の契約（この関数について何が保証されるか）です。
動機: 実装の詳細を説明するドキュメントコメントは、契約を説明するコメントよりも早く古くなります。

内部情報は、ユーザーには関係ない可能性が高いです。関数のドキュメントコメントで、問題を解くために for ループを使っていると説明するとしたら、その情報に何の意味があるでしょうか。
実装を説明する必要がある場合もあるかもしれませんが、それはおそらく、その API の利用者が代わりに認識しておくべき効果や不変条件があるためです。

実装の詳細そのものではなく、それらの効果や不変条件に焦点を当ててください。

繰り返します。実装の詳細は変わりうるだけでなく実際に変わるため、これらの詳細は説明しないでください。
何がどこで使われているかについても触れないでください。これもまた、その情報がすぐに古くなりうる別の例です。

Comprehensive Rust 🦀

「How」と「Where」ではなく、「Why」と「What」