ブロックコメント (Block Comments)

定義

**ブロックコメント (Block Comments)**は、コードだけでは残らない理由、契約、制約を将来の読者へ伝える記録である。タイトル中の「Block Comments」は、この概念を適用する条件または具体的な構成要素を示す。

仕組みと具体例

処理の逐語訳ではなく、非自明な選択理由や単位、外部仕様への依存を書く。実際に適用するときは、通常時だけでなく境界値、失敗、並行実行、外部依存の変化が結果へどう影響するかを追跡する。

実践と検証

実装と同じ変更で更新し、古い説明を検査・削除する。期待する結果を観測可能な条件で記述し、最小の例から始めて異常系を追加する。自動化する場合も、基準自体が妥当かをレビューする。

トレードオフ

この手法の導入は一貫性と再現性を高める一方、設定、抽象、運用対象を増やす場合がある。適用範囲を広げる前に、解決するリスクと維持コストを比較する。例外は暗黙にせず、理由、期限、代替策を記録する。