演習: 詳細をめぐる対話

不要な詳細が、ときには、実際には文書化が必要な何かを示して いることがあります。

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

/// スライスをソートします。再帰的クイックソートを使用して実装されています。
fn sort_quickly<T: Ord>(to_sort: &mut [T]) { ... }

  • 受講者に尋ねる: このコメントはこの関数に必要でしょうか?

  • 進行: PM やマネージャーなど、受講者と作者の間に立つ仲介役を 演じながら、この関数の作者はこのコメントに難色を示していると 受講者に伝えます。

  • 受講者に尋ねる: この種のコメントの作者が難色を示すのはなぜでしょうか?

    受講者が、なぜ作者が難色を示すのかを尋ねても、まだ詳細は伝えないでください。

  • 受講者に尋ねる: 呼び出し側は、使われているソートアルゴリズムを なぜ知る必要があるのでしょうか?

  • 進行: 元の作者との会議から「戻ってきた」ことにして、この関数は 信頼できないデータに対して呼び出されるアプリケーションコードであり、 そのデータは ソート中に二次時間の挙動を引き起こすよう悪意を持って細工される可能性がある と受講者に説明します。

  • 受講者に尋ねる: ここまで詳細がわかった今、この関数にはどのように コメントすべきでしょうか?

    つまり、あることが実装の詳細かどうかは、その公開された契約が何か （たとえば、信頼できないデータを渡せるかどうか）に大きく依存し、 慎重な判断が必要です。

    コメントが for ループを使っていることを説明している場合（不要な 詳細）と、内部で使われるアルゴリズムに既知の悪用手法が存在することを 説明している場合（ドキュメントが注意を向ける先を誤っている）の違いを 考えてください。