コーディングにおけるドキュメンテーションのアンチパターン

まえがき

『ドキュメンテーションは、（略）コードの中身を読まなくても「そのコードが何をするのか・何であるのか」について理解可能にすることが求められます。』

リスト

• 自動生成されたドキュメンテーションを放置する： IDEやエディタが生成するひな型だけでは情報がない。
• 宣言と同じ内容を繰り返す： たとえば getDescription() に対して「説明を取得する」というコメントを付けても意味がない。
• コードを自然言語に翻訳する： 処理を逐一自然言語に直訳しただけではわかりづらい。
• 概要を書かない： 例外的な動作や境界条件だけを書いても、読み手は概要を理解できない。
• 実装の詳細に言及する： たとえばパブリックメソッドの説明にプライベートメンバを使うと、読み手はコードの概要を理解するために実装の詳細まで調べなければならない。
• コードを使う側に言及する： コードの参照元や呼び出し元に言及すると、保守性が落ちる。

あとがき

まえがきを含めて、石川 宗寿『読みやすいコードのガイドライン -持続可能なソフトウェア開発のために』 （技術評論社、2022年）より。リストのうち「：」より手前の部分は本文からの引用です。後ろの部分は本文を編集して作成しました。

ここでいうドキュメンテーションとは、次の /** ～ */ の部分。特に「概要」の部分のアンチパターン（べからず集）です。

このサイトのために結構な量のコードを書いています。自分のコメントを時間が経ってから読み返すとわかりづらいことが多く、本書を手に取りました。

/**
 * 概要
 * 
 * 詳細
 * 
 * @param
 * @return
 */
function getDescription() {
    // 非形式的なコメント
}

• タイトル： 読みやすいコードのガイドライン -持続可能なソフトウェア開発のために
• 著者： 石川 宗寿(著)
• 出版社： 技術評論社
• 出版日： 2022-10-22