# コメント設計 ## 定義 コメント設計とは、コードのインターフェースコメントと実装コメントを通じて、設計者の頭の中にはあってもコード自体には表現できない情報を捉え、抽象を完成させるための実践である。Ousterhout は、コメントの役割を単なる可読性向上の補助にとどめず、抽象化を成立させるための不可欠な構成要素として位置づける。クラスの形式的なインターフェース(メソッドのシグネチャなど)はコードで表現できるが、各メソッドが何をするかの高水準な説明や戻り値の意味、設計判断の根拠、特定のメソッドを呼ぶべき条件といった非形式的な側面はコメントでしか記述できない。(Source: [[@2018__YaknyamPress__A Philosophy of Software Design - Chapter 12 Why Write Comments? The Four Excuses]] §12.1) ## コメントを書かない 4 つの言い訳への反駁 Ousterhout は、開発者がコメントを書かない際に持ち出す 4 つの言い訳を挙げ、それぞれに強い調子で反論する。以下は著者自身の主張であり、本書の立場を表す。 1. **「良いコードは自己文書化されている」**: 著者はこれを「アイスクリームが健康に良いという噂のような、魅力的だが誤った神話」と表現する。コードを読ませてインターフェースを理解させるという発想自体が問題であり、読者に実装を読ませる前提で書かれたコードは各メソッドをできるだけ短くしようとする結果、些細な処理まで細分化された浅いメソッドの集合になりがちで、しかもトップレベルの挙動を理解するには結局ネストしたメソッドまで読む必要があり可読性は向上しない。さらに本質的な論点として、コメントは抽象化そのものに不可欠だと著者は主張する。抽象化とは本質的な情報を保持し無視してよい詳細を省いた単純化された見え方であり、利用者がメソッドの実装コードを読まねば使えないなら、それは抽象化になっていない。コメントなしのメソッドの唯一の抽象はその宣言(名前・引数・戻り値の型)だけであり、有用な抽象を提供するには情報が足りない。コメントは呼び出し元が必要とする追加情報を捉えることで、実装の詳細を隠しながら単純化された見え方を完成させる役割を担う。(Source: [[@2018__YaknyamPress__A Philosophy of Software Design - Chapter 12 Why Write Comments? The Four Excuses]] §12.1) 2. **「コメントを書く時間がない」**: 著者は、コードを実際に打ち込む時間(設計・コンパイル・テスト等を除く)は開発時間全体の 10% を超えないと見積もり、コメントにコードと同じだけの時間をかけても開発時間への上乗せは 10% 程度にとどまると論じる。良い文書化がもたらす保守性向上の便益はこの費用をすぐに上回るとし、投資マインドセットの一環として位置づける。特にクラスやメソッドの最上位文書は、後付けの作業ではなく設計プロセスの一部として書くべきであり、文書化という行為自体が設計を改善する重要な設計ツールとして働くため、こうしたコメントはただちに元が取れると主張する。(Source: [[@2018__YaknyamPress__A Philosophy of Software Design - Chapter 12 Why Write Comments? The Four Excuses]] §12.2) 3. **「コメントは古びて誤解を招く」**: 著者はコメントの陳腐化自体が実務上大きな問題になるとは考えていない。文書化への大きな変更が必要になるのはコードへの大きな変更があったときだけで、コードの変更の方が文書化の変更より時間を要する。重複した文書化を避け、対応するコードの近くに文書を置くという整理さえすれば、修正後も文書を最新に保ちやすいとし、コードレビューを陳腐化したコメントの検出・修正の機構として位置づける。(Source: [[@2018__YaknyamPress__A Philosophy of Software Design - Chapter 12 Why Write Comments? The Four Excuses]] §12.3) 4. **「見てきたコメントはどれも役に立たなかった」**: 著者は 4 つの言い訳の中でこれが最も一理あると認める。有用な情報を提供しないコメントは誰もが見た経験があり、既存の文書化の大半はせいぜい平凡な水準にとどまる。しかしこれを解決不能な問題ではなく、良いコメントの書き方さえ知れば解消できる問題として位置づける。(Source: [[@2018__YaknyamPress__A Philosophy of Software Design - Chapter 12 Why Write Comments? The Four Excuses]] §12.4) 4 つの言い訳を退けたうえで著者が示すコメントの便益は、設計者の頭の中にあった情報を捉えることに集約される。この情報は、あるトリッキーなコードを動機づけるハードウェアの癖のような低水準の詳細から、クラスの存在理由のような高水準の概念まで幅広い。良い文書化は複雑性の 3 症状のうち認知負荷と未知の未知の 2 つを軽減し、複雑性の主因である依存と不明瞭さについても、依存関係を明確化し不明瞭さを埋めて解消する。(Source: [[@2018__YaknyamPress__A Philosophy of Software Design - Chapter 12 Why Write Comments? The Four Excuses]] §12.5) ## 何をどう書くか 第 12 章がコメントを書くべき理由(4 つの言い訳への反駁)を扱うのに対し、本節は「何をどう書くか」という規約と技法を扱う。 **4 種類の分類(規約として決めておく)**: 著者はコメントを (1) インターフェースコメント(モジュール=クラス・データ構造・関数・メソッドの宣言直前に置き、そのインターフェース=抽象を説明する)、(2) データ構造メンバのコメント(フィールド宣言の脇に置く)、(3) 実装コメント(メソッド内部の動作を説明する)、(4) 横断的コメント(モジュール境界をまたぐ依存を説明する)の 4 種類に分類する。最重要なのは (1)(2) で、すべてのクラス・クラス変数・メソッドが持つべきである。(3) はしばしば不要、(4) は最も稀だが書けたときの価値が最も高い。コメントを書く前に規約を決めることは、一貫性を確保するだけでなく「何を書くべきか分からず結局何も書かない」という事態を防ぐ効果も持つ。(Source: [[@2018__YaknyamPress__A Philosophy of Software Design - Chapter 13 Comments Should Describe Things that Aren't Obvious from the Code]] §13.1) **コードを繰り返さない**: 最もありふれた失敗は、コメントがコード次第で容易に導出できる情報しか含まないことである。判定基準は「そのコードを見たことがない人が、コード脇のコメントだけを見て同じコメントを書けるか」であり、書けてしまうならそのコメントには価値がない。典型例は、メソッド名・変数名を構成する単語をそのまま並べ替えて文にしただけのコメントである。これは著者がレッドフラグ **Comment Repeats Code** と名付けた症状である。(Source: [[@2018__YaknyamPress__A Philosophy of Software Design - Chapter 13 Comments Should Describe Things that Aren't Obvious from the Code]] §13.2) > [!warning] レッドフラグ: Comment Repeats Code(コメントがコードを繰り返す) > コメントの内容がコード脇のコードから容易に導出できるなら、そのコメントは役に立たない。典型例は、コメントが説明対象の名前を構成する単語をそのまま並べ替えて文にしただけの場合である。 **低水準コメントは精度、高水準コメントは直感**: コメントがコードを補う方向は 2 つある。低水準コメントはコードより詳細な情報(単位、境界条件が両端を含むか、null の意味、リソースの解放責任者、常に成り立つ不変条件)を加えて精度を高め、主に変数宣言の文書化に有効である。高水準コメントは詳細を省き、コードの意図と全体構造の理解を助けて直感を高める。コードと同水準のコメントはどちらの価値も持たず、コードの繰り返しになりやすい。変数を文書化するときはどう操作されるか(動詞)ではなく何を表すか(名詞)に注目すべきである。(Source: [[@2018__YaknyamPress__A Philosophy of Software Design - Chapter 13 Comments Should Describe Things that Aren't Obvious from the Code]] §13.3〜13.4) **インターフェース文書を実装の詳細で汚染しない**: インターフェースコメントは利用者が抽象を使うために必要な情報だけを含むべきで、実装の詳細を混入させてはならない。メソッドのインターフェースコメントには、(a) 呼び出し元から見た振る舞いの高水準な説明、(b) 各引数・戻り値の制約と引数間の依存関係、(c) 副作用(戻り値以外で将来の挙動に影響する結果)、(d) 発生しうる例外、(e) 呼び出し前に満たすべき前提条件、の 5 要素を含める。これに反しインターフェース文書が実装の詳細を含んでしまう症状を著者はレッドフラグ **Implementation Documentation Contaminates Interface** と呼び、この分離を保てないこと自体がモジュールが浅いことの兆候にもなりうるとする(第 15 章に接続)。(Source: [[@2018__YaknyamPress__A Philosophy of Software Design - Chapter 13 Comments Should Describe Things that Aren't Obvious from the Code]] §13.5) > [!warning] レッドフラグ: Implementation Documentation Contaminates Interface(実装文書がインターフェースを汚染する) > メソッドなどのインターフェース文書が、それを使うために不要な実装の詳細を含んでいるときに生じる。利用者を無用な情報にさらすだけでなく、インターフェースと実装を分離できていないこと自体が、そのモジュールが浅いことの兆候になりうる。 **実装コメントは what と why、how は書かない**: 実装コメントの主目的は、コードが「どうやって」動くかではなく「何を」しているかを読者に理解させることである。短く単純なメソッドは実装コメントを不要とし、長いメソッドでは各ブロック・ループの直前に高水準な要約コメントを置く。加えて、コードのトリッキーな側面がなぜ必要かという why も書くべきで、バグ修正の理由やバグ追跡システムの issue 番号への参照が例に挙がる。(Source: [[@2018__YaknyamPress__A Philosophy of Software Design - Chapter 13 Comments Should Describe Things that Aren't Obvious from the Code]] §13.6) **モジュールをまたぐ設計判断をどこに書くか**: モジュールをまたぐ設計判断は複雑で微妙になりやすく、多くのバグの温床になるため文書化が重要である。最大の課題は開発者が自然に発見できる置き場所を見つけることである。新しい値を追加する際に必ず訪れる場所(enum 宣言など)のように明白な中心的置き場所があればそこに書く。なければ、複数箇所への複製(整合性維持が困難)や単一箇所への配置(発見されにくい)の代わりに、`designNotes` のような一元的な設計ノートファイルに文書を集約し、依存箇所からは短い参照コメントで指し示す方式が有効である。(Source: [[@2018__YaknyamPress__A Philosophy of Software Design - Chapter 13 Comments Should Describe Things that Aren't Obvious from the Code]] §13.7) **「明白」の判定基準**: 章題どおり、コメントが描写すべきなのはコードから明白でないことに限られる。この「明白かどうか」は書き手ではなく、コードを初めて読む読み手の視点から判断されるべきである。コードレビューで「これは明白でない」と指摘されたら反論せず、レビューアが何を分かりにくいと感じたかを理解してコメントかコードを改善すべきである。(Source: [[@2018__YaknyamPress__A Philosophy of Software Design - Chapter 13 Comments Should Describe Things that Aren't Obvious from the Code]] §13.8) ## コメントを先に書く(コメントファースト) 第 12 章・第 13 章が「なぜ書くか」「何をどう書くか」を扱うのに対し、本節はコメントを**書く時点(タイミング)**という 3 つ目の軸を扱う。著者はコメントを開発の最後まで先延ばしにする慣行を、質の低い文書化を生む最も確実な方法だと述べる。先延ばしを始めるとさらに先延ばしをしやすくなり、コードが安定した頃には量が膨大になって文書化の作業がますます魅力を失うという悪循環に陥る。仮に自制心があって後から書き戻したとしても、その時点では設計時の記憶が薄れており、コードを見ながら書くコメントはコードの繰り返しになりがちで、設計意図のうち覚えていない部分は欠落する。(Source: [[@2018__YaknyamPress__A Philosophy of Software Design - Chapter 15 Write The Comments First]] §15.1) 著者はこれに対して「コメントファースト(comments-first approach)」という具体的な手順を示す。新しいクラスに対して、まずクラスインターフェースコメントを書き、次に重要な public メソッドのシグネチャとインターフェースコメントを本体を空のまま書く。この構造にひととおり納得できるまで反復したあと、重要なインスタンス変数の宣言とコメントを書く。最後にメソッド本体を実装し、必要に応じて実装コメントを加える。実装の過程で新たに必要になったメソッドやインスタンス変数についても、本体より先にコメントを書く。コードが完成した時点でコメントも完成しており、未執筆コメントの残債は生じない。(Source: [[@2018__YaknyamPress__A Philosophy of Software Design - Chapter 15 Write The Comments First]] §15.2) **コメントは設計ツールである**というのが、著者がコメントファーストに与える最重要の位置づけである。コメントは抽象を完全に捉える唯一の手段であり、良い抽象は良い設計の基盤である。設計の最初に抽象を記述するコメントを書けば、実装コードを書く前にそれをレビューし調整できる。良いコメントを書くには変数やコードの本質、すなわち最も重要な側面が何かを見極めなければならず、これを設計プロセスの早い段階で行わないと単なるコードのハッキングになってしまう。この考え方から、コメントは**複雑性の炭鉱のカナリア**として機能する。メソッドや変数の説明に長く複雑なコメントが必要になるなら、それは良い抽象を持てていないことを示すレッドフラグである。インターフェースコメントが短く単純でありながらメソッドの使用に必要な情報をすべて提供できるなら、そのメソッドは単純なインターフェースを持つ深いメソッドであり、逆に実装の主要な特徴をすべてインターフェースコメントに書かねばならないなら、そのメソッドは浅い。同じ考え方は変数にも当てはまる。ただしこれが複雑性の良い指標として機能するのは、コメント自体が完全かつ明快である場合に限られ、情報不足で難解なコメントはメソッドの深さを測る指標にはならない。(Source: [[@2018__YaknyamPress__A Philosophy of Software Design - Chapter 15 Write The Comments First]] §15.3) > [!warning] レッドフラグ: Hard to Describe(説明しづらい) > メソッドや変数を説明するコメントは単純かつ完全であるべきである。そのようなコメントを書くのが難しいなら、それは説明対象の設計に問題があることを示す指標である。 著者は「早期のコメントは楽しいコメントである(early comments are fun comments)」とも述べる。これは著者自身の経験に基づく主張であり、新しいクラスの抽象と構造を組み立てる早期の設計段階がプログラミングで最も楽しい部分の 1 つであり、コメントの大半はこの段階で書かれ、設計判断の質を記録し検証する手段になるという。最も少ない語数で完全かつ明快に表現できる設計を探すことが目的であり、コメントが単純であるほど設計への手応えが増し、単純なコメントを見つけること自体が誇りの源になると著者は語る。(Source: [[@2018__YaknyamPress__A Philosophy of Software Design - Chapter 15 Write The Comments First]] §15.4) コメントファーストはまた、「コメントを書く時間がない」という言い訳(第 12 章)への具体的な反証としても機能する。コードとコメントを打ち込む時間(改訂を含む)は開発時間全体の 10% を超えることはまずなく、コード行の半分がコメントだとしても、コメント執筆自体は開発時間全体の 5% 程度にしかならない。コメントを最後まで遅らせても、そのうちのごく一部しか節約できない。むしろ先にコメントを書けば、コードを書き始める前に抽象が安定するためコーディング中の時間を節約できる可能性が高く、先にコードを書く場合はコーディングの過程で抽象が変化しやすくより多くのコード改訂を要する。これらを総合すると、コメントを先に書くほうが全体としてはむしろ速い可能性があると著者は結論づける。(Source: [[@2018__YaknyamPress__A Philosophy of Software Design - Chapter 15 Write The Comments First]] §15.5) ## コメントの保守(既存コードを変更するとき) 第 12 章・第 13 章・第 15 章がコメントを「書く」局面(なぜ・何を・いつ)を扱うのに対し、第 16 章はコメントを既存コードの変更に合わせて**保守する**局面を扱う。既存コードを変更すると、その変更が既存コメントを陳腐化させることが多い。コメントの更新を忘れやすく、放置すると不正確なコメントが増え、読者はやがてコメント全体を信用しなくなる。著者はこれに対して規律とわずかな技法で対処できるとし、以下の具体的な技法を示す。(Source: [[@2018__YaknyamPress__A Philosophy of Software Design - Chapter 16 Modifying Existing Code]] §16.2) **コメントを説明対象のコードの近くに置く**: コメントを最新に保つ最善の方法は、コメントを説明対象のコードの近くに置き、コードを変更する開発者がそのコメントを自然に目にするようにすることである。コメントが説明対象から物理的に離れているほど、正しく更新される見込みは下がる。メソッドのインターフェースコメントの最善の置き場所はヘッダファイルではなくコード本体、メソッド本体の直前である。C/C++ のように `.h` ファイルにインターフェース宣言を分離する言語では、その `.h` ファイルにインターフェースコメントを置く流儀もあるが、これはコードから遠く、開発者はメソッド本体を変更する際にそのコメントを目にせず、更新するには別ファイルを開いて探す手間がかかる。利用者はコードやヘッダファイルを読まずとも、Doxygen や Javadoc のようなツールが生成する文書、あるいは IDE がメソッド名の入力時に提示する文書から情報を得るべきであり、文書化は開発者にとって最も都合のよい場所、すなわちコード本体の近くに置くべきだと著者は主張する。実装コメントについても、メソッド冒頭にすべてをまとめて書くのではなく、コメントが説明する範囲の最も狭いスコープの直前まで押し下げて分散させる。一般に、コメントが説明対象のコードから離れているほど、そのコメントはより抽象的であるべきであり、これがコード変更によってコメントが無効化される可能性を下げる。(Source: [[@2018__YaknyamPress__A Philosophy of Software Design - Chapter 16 Modifying Existing Code]] §16.2) **コメントはコードに書く、コミットログには書かない**: 著者は、変更に関する詳細情報をコミットメッセージにだけ書き、コードには文書化しないことをよくある誤りとして名指しする。これは著者自身の強い主張であり、根拠として将来の読み手が実際にどこを見るかという実務上の観察を挙げる。コミットメッセージは将来リポジトリのログを走査すれば読めるが、情報を必要とする開発者がログを走査しようと思いつくことはまずなく、仮に走査しても目的のログメッセージを見つけるのは煩雑である。著者は、コミットメッセージを書くときは「開発者が将来この情報を必要とするか」を自問し、必要ならその情報をコード自体に文書化すべきだと述べる。ある変更を動機づけた微妙な問題がコードに記載されていなければ、後から来た開発者がその問題を理解せずに変更を取り消し、バグを再び作り込んでしまうことがある。コミットメッセージに同じ情報の複製を残すこと自体は構わないが、最も重要なのはその情報をコードに入れることである。これは、文書化は開発者が実際に見る場所に置くべきだという原則の一例であり、コミットログはめったにその場所ではないと著者は結論づける。(Source: [[@2018__YaknyamPress__A Philosophy of Software Design - Chapter 16 Modifying Existing Code]] §16.3) **重複させない**: コメントを最新に保つもうひとつの技法は文書化の重複を避けることである。文書化が重複していると、開発者が関連するすべてのコピーを見つけて更新するのが難しくなる。各設計判断はちょうど一箇所にだけ文書化すべきであり、複数箇所がある決定に影響される場合でも各箇所に文書を繰り返してはならない。単一の明白な置き場所が見当たらないときは、第 13 章 §13.7 の `designNotes` ファイルのような集約先を作るか、利用可能な場所の中から最善のものを選び、他の関連箇所には「xyz のコメントを参照」という短い参照コメントを添える。参照先の中心コメントが移動・削除されて参照が陳腐化しても、開発者は指し示された場所にコメントが見当たらないという形でその不整合に気づけるため、リビジョン管理の履歴を辿って参照を更新できる。これに対して文書化が重複していて一部のコピーが更新されない場合、開発者にはそれが古い情報だという手がかりが何も与えられない。あるモジュールの設計判断を別のモジュールで再文書化することも避けるべきで、あるメソッドの呼び出し箇所の直前にそのメソッド内部の動作を説明するコメントを書くべきではない。読者が知りたければそのメソッドのインターフェースコメントを見るべきである。プログラムの外部にすでに文書化されている情報(プロトコル仕様やユーザマニュアル記載のコマンド説明など)も、プログラム内で繰り返さず外部文書への短い参照だけを添える。(Source: [[@2018__YaknyamPress__A Philosophy of Software Design - Chapter 16 Modifying Existing Code]] §16.4) **コードレビューの差分確認に組み込む**: 文書化を最新に保つ良い方法のひとつは、リビジョン管理システムにコミットする前に数分かけてその変更の差分をすべて見直し、各変更が文書化に正しく反映されているか確認することである。このコミット前の差分確認は、デバッグ用コードの消し忘れや TODO 項目の未対応といった他の問題も検出する。(Source: [[@2018__YaknyamPress__A Philosophy of Software Design - Chapter 16 Modifying Existing Code]] §16.5) **高水準なコメントほど保守しやすい**: コメントは、それが説明するコードより高水準で抽象的であるほど保守しやすい。そうしたコメントはコードの細部を反映しないため軽微なコード変更の影響を受けにくく、全体の振る舞いが変わったときだけ更新が必要になる。もっとも第 13 章で論じたとおり、詳細で精密であるべきコメントも存在する。しかし一般に、コードを単に繰り返さない有用なコメントは保守しやすいコメントでもある。(Source: [[@2018__YaknyamPress__A Philosophy of Software Design - Chapter 16 Modifying Existing Code]] §16.6) ## 横断的知見 - 第 12 章は「なぜコメントを書くか」(4 つの言い訳への反駁と、コメントが複雑性の症状のうち認知負荷・未知の未知を軽減するという便益論)を扱うのに対し、第 13 章は同じ「コメントは設計者の頭の中にある情報を捉える」という前提の上で「何をどう書くか」という規約・技法(4 分類・精度と直感の二方向・インターフェースと実装の分離・what/why と how の区別)に踏み込む。両章は理由と方法という補完関係にあり、第 13 章の実践的な書き方の指針は、第 12 章が説く「コメントは抽象化に不可欠である」という主張を具体化したものと位置づけられる。(Source: [[@2018__YaknyamPress__A Philosophy of Software Design - Chapter 12 Why Write Comments? The Four Excuses]], [[@2018__YaknyamPress__A Philosophy of Software Design - Chapter 13 Comments Should Describe Things that Aren't Obvious from the Code]]) - 第 12 章はコメントを書かない言い訳の 1 つとして「コメントを書く時間がない」を挙げ、投資マインドセットの観点から反駁するにとどまる(§12.2)。第 15 章はこれに対し、コード・コメント併せた執筆時間が開発時間全体の 1 割程度に過ぎないという概算(§15.5)を示すことで、同じ言い訳に対するより具体的で定量的な反証を与える。両章は「時間がない」という言い訳を、第 12 章が投資対効果の一般論で、第 15 章が時間配分の実測見積もりで、二重に切り崩す関係にある。(Source: [[@2018__YaknyamPress__A Philosophy of Software Design - Chapter 12 Why Write Comments? The Four Excuses]] §12.2, [[@2018__YaknyamPress__A Philosophy of Software Design - Chapter 15 Write The Comments First]] §15.5) - 第 13 章はインターフェース文書が実装の詳細で汚染される症状(レッドフラグ Implementation Documentation Contaminates Interface, §13.5)を「モジュールが浅いことの兆候」と位置づけたが、第 15 章はこの接続をコメントファーストの手順の中でさらに一般化し、インターフェースコメントの長さ・複雑さそのものをモジュールの深さを測る指標(レッドフラグ Hard to Describe, §15.3)として使う。すなわち第 13 章は「インターフェースコメントに実装が混入していないか」という分離の視点で浅さを検出し、第 15 章は「インターフェースコメントが短く単純に書けるか」という記述の容易さの視点で浅さを検出する。両者は同じ「深いモジュール」概念を異なる角度から具体化している。(Source: [[@2018__YaknyamPress__A Philosophy of Software Design - Chapter 13 Comments Should Describe Things that Aren't Obvious from the Code]] §13.5, [[@2018__YaknyamPress__A Philosophy of Software Design - Chapter 15 Write The Comments First]] §15.3) - 第 15 章のコメントファーストと第 16 章のコメント保守は「いつ書くか」と「どう維持するか」で対をなす。第 15 章はコメントを実装より先に書くことで設計プロセスの一部にし、未執筆コメントの残債が生じないようにする(§15.2)。しかしコメントファーストで書かれたコメントも、後から既存コードを変更すれば陳腐化しうる点は避けられない。第 16 章はこの陳腐化を防ぐ技法(近接配置・コミットログではなくコードに書く・重複回避・diff 確認・高水準化)を示すことで、コメントファーストが生んだ初期の完全なコメント群を維持する側を担う。両章を合わせると、コメントのライフサイクルは「設計段階で先に書く(第 15 章)→ 変更のたびに近くで保守する(第 16 章)」という一貫した流れになる。(Source: [[@2018__YaknyamPress__A Philosophy of Software Design - Chapter 15 Write The Comments First]], [[@2018__YaknyamPress__A Philosophy of Software Design - Chapter 16 Modifying Existing Code]]) - 第 13 章 §13.7 で導入された `designNotes` ファイルは、第 16 章 §16.4 では「重複を避けつつ単一の明白な置き場所がない設計判断を集約する」技法として再登場する。第 13 章はモジュールをまたぐ設計判断の置き場所という文脈で導入したのに対し、第 16 章はコメント保守全般(重複回避)の文脈でこれを一般化しており、同じ機構が異なる問題設定から独立に要請されている。(Source: [[@2018__YaknyamPress__A Philosophy of Software Design - Chapter 13 Comments Should Describe Things that Aren't Obvious from the Code]] §13.7, [[@2018__YaknyamPress__A Philosophy of Software Design - Chapter 16 Modifying Existing Code]] §16.4) ## 未解決の問い - 「文書化を設計プロセスの一部として先に書く」という主張(第 12 章 §12.2)は第 15 章でコメントファーストという具体的な手順として展開されることが分かった。一方、インターフェースコメントと実装コメントの分離が保てないことが「モジュールが浅い兆候になる」(第 13 章 §13.5)という接続についても、第 15 章はコメントの長さ・複雑さ自体を深さの指標とする形で発展させている。この 2 つの「浅さの検出方法」(実装の混入の有無/記述の容易さ)を統一的にどう使い分けるべきかは、両章の記述からは明確でない。 - コメントの 4 分類のうち横断的コメント(cross-module comment)の `designNotes` 方式は、コードから物理的に離れるため最新性を保ちにくいという欠点が本章で述べられている。第 16 章 §16.4 は参照コメントの陳腐化がリビジョン管理履歴で発見可能だとするが、この欠点への根本対策や、実際にどの程度陳腐化するかは論じられていない。 - コメントファーストの手順(§15.2)は個々の開発者の作業手順として示されているが、チーム開発でのコードレビューや複数人での協業の中でこの手順をどう運用するかは第 15 章では論じられていない。 - 第 16 章 §16.5 が示すコミット前差分確認は個人の習慣として提示されるが、これをコードレビューのプロセス(他者によるレビュー)にどう組み込むべきか、レビュー観点として明文化した規約は本書のこれまでの章では示されていない。 ## 関連 - 章: [[@2018__YaknyamPress__A Philosophy of Software Design - Chapter 12 Why Write Comments? The Four Excuses]] / [[@2018__YaknyamPress__A Philosophy of Software Design - Chapter 13 Comments Should Describe Things that Aren't Obvious from the Code]] / [[@2018__YaknyamPress__A Philosophy of Software Design - Chapter 15 Write The Comments First]] / [[@2018__YaknyamPress__A Philosophy of Software Design - Chapter 16 Modifying Existing Code]] - 実体: [[wiki/entities/A Philosophy of Software Design|A Philosophy of Software Design]] / [[John Ousterhout]] - 概念: [[深いモジュール]] / [[抽象化(ソフトウェア設計)]] / [[戦略的プログラミング]] / [[ソフトウェア保守]] ## 出典 - John Ousterhout, *A Philosophy of Software Design*, Yaknyam Press, 2018, Chapter 12. - John Ousterhout, *A Philosophy of Software Design*, Yaknyam Press, 2018, Chapter 13. - John Ousterhout, *A Philosophy of Software Design*, Yaknyam Press, 2018, Chapter 15. - John Ousterhout, *A Philosophy of Software Design*, Yaknyam Press, 2018, Chapter 16.