名前とシグネチャは完全なドキュメントではない

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

// 悪い例
/// 操作が完了したときに解決される future を返します。  
fn sync_to_server() -> Future<Bool>;

// 良い例
/// ローカルの編集内容をサーバーに送信します。競合する編集があった場合は、  
/// それらを上書きします。  
fn sync_to_server() -> Future<Bool>;

// 悪い例
/// メールの送信に失敗した場合はエラーを返します。  
fn send(&self, email: Email) -> Result<(), Error>;

// 良い例
/// メールをバックグラウンド配信のためにキューに入れ、すぐに返ります。  
///
/// メールの形式が不正な場合は、即座にエラーを返します。  
fn send(&self, email: Email) -> Result<(), Error>;

  • 動機: API 設計者は、関数名とシグネチャだけで十分なドキュメントになるという考えに過度にコミットしてしまうことがあります。

  • 繰り返しになりますが、名前と型はドキュメントの 一部 です。常にそれだけで全体像を語れるわけではありません。

  • 関数の名前、パラメータ名、またはその関数のシグネチャではカバーされない関数の振る舞いを考えてください。

    • sync_to_server() が何かを上書きする可能性があること（データ損失につながる）は明白ではないため、それを文書化します。

    • メールの例では、その関数が成功を返してもメールの配信には失敗する可能性があることは明白ではありません。

  • 曖昧さをなくすためにコメントを使います。ニュアンスのある振る舞いや、API の利用者がつまずく可能性のある振る舞いは、文書化するべきです。