rinkou_12

Transcript

1. Chapter 12 Why Write Comments? The Four Excuses 1
2. Chapter 12 なぜコメントを書くのか？ 4つの言い訳 2
3. なぜコメントを書くのか？① コード内のドキュメント（コメント）は、ソフトウェア設計において極めて重要な役 割を果たす 3
4. なぜコメントを書くのか？② ドキュメントとは ソフトウェアの「文書化（概念・目的） 」 「抽象化」を成立させ、設計品質を支える コメントとは コード内の「記述（具体的な手段） 」 開発者の理解を助け、複雑さを隠蔽する 4
5. なぜコメントを書くのか？③ 正しくコメントを書くプロセスそのものが、結果としてシステムの設計を向上さ せることにつながる 逆に言えば、優れたソフトウェア設計であっても、ドキュメントが不十分であれ ばその価値の多くが失われてしまう 5
6. 開発者がコメントを書かないときの言い訳 優れたコードは、それ自体がドキュメントである コメントを書く時間がない コメントは古くなり、誤解を招く元になる 今まで見てきたコメントはどれも価値がなかった 6
7. 12.1 優れたコードは、それ自体がドキュメントである① コードを改善してコメントを減らすことは可能だが、コードだけで全ての設計意 図を表現することはできない メソッドの役割、戻り値の意味、設計の根拠（なぜそうしたか） 、呼び出し時の前 提条件などは、コメントでしか説明できない 実装を読ませる前提だと、メソッドを細切れにしすぎる傾向があり、結果として 「中身の薄いメソッド」が増えて全体像が把握しづらくなる 7
8. 12.1 優れたコードは、それ自体がドキュメントである② 大規模システムにおいて、挙動を知るために逐一ソースコードを読むのは非効率で 苦痛 抽象化とは「詳細を隠して本質を見せる」こと。実装を読まなければ使い方がわ からない状態は、抽象化が失敗していることを意味する コメントは自然言語で書かれるため、表現力が豊かであり、シンプルで直感的な 説明を可能にする 8
9. 12.2 コメントを書く時間がない 常に新機能の開発などは優先度が高く感じられるため、ドキュメントを後回しに すると、最終的に全く書かれないことになる 長期的に効率を高めるには、最初に少しの時間を投資してクリーンな構造を作る 必要がある。優れたコメントは保守性を高め、費やした労力はすぐに回収できる クラスやメソッドの概要など、抽象化に関するコメントは設計段階で書くべきで あり、ドキュメント化というプロセス自体が設計を改善する役割を果たし、即座 にメリットをもたらす 9
10. 12.3 コメントは古くなり、誤解を招く元になる ドキュメントを最新の状態に保つために、それほど膨大な労力は必要ない ドキュメントの大量修正があったとしても、コードの修正にかかる時間に比べた ら少ない 第16章で、コードの修正後にドキュメントをできるだけ簡単に更新できるように するための整理術について解説がある 10
11. 12.4 今まで見てきたコメントはどれも価値がなかった 言い訳の中ではこれが一番説得力がある 世の中には質の低いドキュメントが蔓延しているものの、書き方さえ知れば、優 れたドキュメントを作成することは難しくない 11
12. 12.5 優れたコメントがもたらすメリット①：保守性 別の開発者が修正を加える際、コメントがあれば、より迅速かつ正確に作業を進 めることができる たとえ修正を行うのが設計者本人であっても、設計から数週間経てば忘れて しまうため、未来の自分のためにもなる 12
13. 12.5 優れたコメントがもたらすメリット②：複雑さの管理 複雑さへの対処（第2章の課題解決） 「認知負荷」の軽減 必要な情報を整理し、不要な情報の切り捨てを容易にする 「未知の未知」の解消 システム構造を明確にし、修正時にどこに影響が出るかを把握しやすく する 優れたドキュメントは依存関係を明確にし、情報の欠落を補うことで不透明さを 解消する 13
14. 12.6 異なる見解：コメントは「敗北」である① ロバート・マーティンの主張（ 『Clean Code』より） コメントは「必要悪」であり、コードで意図を表現しきれなかったことによ る「敗北」の証である プログラミング言語を完璧に使いこなせれば、コメントは本来不要なはずだ 著者の反論：コメントは敗北ではない コメントが提供する情報はコードとは根本的に異なる種類のものであり、コ ードだけで代用することはできない 適切に書かれたコメントがあれば、開発者は中身のコードを全て読まなくて も、その機能を正しく利用できる 14
15. 12.6 異なる見解：コメントは「敗北」である② マーティンの哲学によって「コメントを書いたら敗け」という風潮が広まること を著者は懸念している コメントは決して敗北などではない。質の高いコメントは、コードの価値を高 め、複雑なシステムを管理するために不可欠な要素である 15