# 目次
# はじめに
以下の記事は，オライリージャパン社から出版された
『プログラマが知るべき97のこと』
の中から1つのエッセイを選び，
そのエッセイを，クリエイティブコモンズ3.0の条件の元で転載したものです．
Creative Commons ― 表示 3.0 アメリカ合衆国 ― CC BY 3.0
本書の内容は，オープンソースモデルに従い，
ほぼ無制限で利用が可能です．
クリエイティブ・コモンズ表示3.0の条件下で，
自由に使用することができるのです．
つまり，どのエッセイも，
著者の名前を明記すれば，自由に転載，改変が可能であるということです．
ーー"はじめに"から抜粋 pXII
もし，他のエッセイを読みたい場合には，
記事末のリンクを辿るか，
以下のリンク先のTwitterアカウントのつぶやきからお探し下さい．
Twitter Account: 97 Things Bot
また，元の英文によるエッセイを読みたい方は，
こちらを参照して下さい．
Contributions Appearing in the Book - Programmer 97-things
17. コードに書けないことのみをコメントにする ケブリン・ヘニー (Kevlin Henney)：『プログラマが知るべき97のこと』
「理論と実践は違う」
とよく言われますが，
その違いは，
自分で何かを実践してみると本当によくわかります．
これは，
コードにつけるコメントについても当てはまることです．
コードにコメントをつけるのは，
理論的には良いこととされています．
「これはどういう処理をするコードなのか」を
コメントで詳しく説明するのは，
良いこと，役に立つこととされているのです．
しかし実際には，コメントを入れたことが
かえって害になる場合もよくあります．
世の中には「文章術」というものがありますが，
コメントにも良いコメントを書くための文章術があるのです．
中でも特に大事なのが，
コメントに「書かなくてもよいこと」を見極める技術でしょう．
文法的に誤ったコードを書けば，
コンパイラやインタープリタ等のツールがエラーを発生させ，
それを知らせてくれます．
また，コードに機能的な問題があれば，
レビューや静的分析で発見されることもあるし，
製品になってユーザが日々使うなかで発見されることもあります．
しかし，コメントはどうでしょうか？
『プログラム書法』
共立出版
売り上げランキング: 274529
という本の中で，
著者のKernighanとPlaugerは
「たとえコメントを入れても，
それが不適切なものであれば，
価値はゼロ（あるいはマイナス）である」
と述べています．
そして，こうした不適切なコメントは
不適切なコードとは異なり，
修正されたり，削除されたりすることは少なく，
コードベースにいつまでも残ってしまうことが多いのです．
不適切なコメントが残っていれば，
誰かがコードを見る度に集中力が削がれたり，
誤った情報を与えてしまうことさえあります．
ほんのわずかでも，
絶えず，プログラマにとっての思考の妨げになってしまうのです．
書いていることが技術的に誤っているわけではないが，
コードに何か価値を加えるわけでもない，
そういったコメントは，
一種の「ノイズ」だとみなすことができます．
コードに書かれていることをただオウム返しにするだけでは，
何の情報もつけ加えていないコメントはノイズでしょう．
プログラミング言語で一度書いたことを，
もう一度，自然言語が言ったところで，
正しさが増すなどということはありません．
コメントの部分は，実行されるわけではないので，
ノイズのようなコメントは，
コードを読むときにも，実行する時にも
まったく役に立たないのです．
また，コメントの内容は，
あっという間に陳腐化する，
という点にも注意が必要です．
たとえば，このコードがどのバージョンなのかを知らせるコメントや，
「どのバージョンでどういう修正を加えたのか」
という履歴を入れてコメントアウトされたコードなどがよくありますが，
そのような情報はバージョン管理システムを使えば，
（はるかに合理的に）得ることができます．
ノイズのようなコメント，
情報の誤ったコメントがコードベースに大量にあると，
やがてプログラマはコメントのすべてを無視するようになります．
ただ読み飛ばすという人もいれば，
コメントが画面から消えるよう対策を講じる人もいます．
プログラマという人種は皆，
問題を回避することに長けています．
自分にとって害になり得るものの存在を察知すれば，
すぐにそれを避ける方法を見つけ出します．
コメントの部分を「折り畳める」ようにしたり，
あるいはコメント部分の色を背景を同じにして，
見えなくしてしまうこともできます．
コメントをフィルタリングするスクリプトを書く人もいるでしょう．
しかし，プログラマののせっかくの能力を
そんなことに使用することは無駄です．
それに中には本当に価値のある，
重要なコメントもあるはずなので，
それを見逃すのは問題です．
こういう問題を防ぐには，
コメントを通常のコードとまったく同じように考えて
扱うことが重要になってきます．
すべてのコメントを読む人にとって価値あるものとし，
そうでもないものは即座に削除するか，
書き直すべきであるということです．
「読む人にとって価値がある」
とは具体的にどういう意味でしょうか？
それは，コードには書いていないことや，
コードには書けない事が書いてある，
ということです．
本来，コードを見ればわかるはずのことを
コメントに書かなくてはならないのは，
コードの構造や書き方を見直す必要があるということです．
メソッドやクラスの名前がわかりにくいから，
コメントを書くというのならば，
名前の方を変えてしまった方がいいでしょう．
関数が長くてわかりにくいせいでコメントが必要ならば，
関数を分割して，どういう関数なのかをすぐに分かる名前を
それぞれの関数に付ける方がいいでしょう．
コード自身にできる限り「語らせる」ようにするのです．
どうしてもコードに語らせることが不可能な時に，
語らせたかった内容と，コードとのギャップこそコメントに書くべきです．
コードに「書いていないこと」ではなく，
コードに「書けない事」のみをコメントにするのです．
■著者データ
[ケブリン・ヘニー (Kevlin Henney)]
フリーのコンサルタント，トレーナー．
特に力をいれているのは，
パターン，アーキテクチャ，プログラミングテクニック，
言語，開発プロセス，プラクティスなど．
「The Register」「Better Software」「Java Report」「CUJ」「C++ Report」
などをはじめとする数々の雑誌，オンライン媒体への寄稿もしている．
Wiley刊行の書籍々
「Pattern Oriented Software Architecture」シリーズ(POSAとして知られる）
のうちの二冊，
『Pattern-Oriented Language for Distributed Computing』
Wiley
売り上げランキング: 92377
『On Patterns and Pattern Languages』
Wiley
売り上げランキング: 112896
の共著者でもある．
『ソフトウェアアーキテクトが知るべき９７のこと』
オライリージャパン
売り上げランキング: 68572
の寄稿者の一人．
また，本書の編者でもある．
関連記事
1．分別のある行動 Seb Rose：『プログラマが知るべき97のこと』 - MY ENIGMA
2．関数プログラミングを学ぶことの重要性 Edward Garson：『プログラマが知るべき97のこと』 - MY ENIGMA
3．ユーザが何をするかを観察する (あなたはユーザではない) Giles Colborne：『プログラマが知るべき97のこと』 - MY ENIGMA
4．コーディング規約を自動化する Filip van Laenen：『プログラマが知るべき97のこと』 - MY ENIGMA
5．美はシンプルさに宿る Jorn Olmheim：『プログラマが知るべき97のこと』 - MY ENIGMA
6．リファクタリングの際に注意すべきこと Rajith Attapattu：『プログラマが知るべき97のこと』 - MY ENIGMA
7．共有は慎重に Udi Dahan：『プログラマが知るべき97のこと』 - MY ENIGMA
8. ボーイスカウト・ルール Robert C. Martin：『プログラマが知るべき97のこと』 - MY ENIGMA
9. 他人よりまず自分を疑う Allan Kelly：『プログラマが知るべき97のこと』 - MY ENIGMA
10. ツールの選択は慎重に Giovanni Asproni：『プログラマが知るべき97のこと』 - MY ENIGMA
11. ドメインの言葉を使ったコード Dan North：『プログラマが知るべき97のこと』 - MY ENIGMA
12. コードは設計である Ryan Brush：『プログラマが知るべき97のこと』 - MY ENIGMA
13. コードレイアウトの重要性 Steve Freeman：『プログラマが知るべき97のこと』 - MY ENIGMA
14. コードレビュー Mattias Karlsson：『プログラマが知るべき97のこと』 - MY ENIGMA
13. コードレイアウトの重要性 Steve Freeman：『プログラマが知るべき97のこと』 - MY ENIGMA
14. コードレビュー Mattias Karlsson：『プログラマが知るべき97のこと』 - MY ENIGMA
MyEnigma Supporters
もしこの記事が参考になり、
ブログをサポートしたいと思われた方は、
こちらからよろしくお願いします。
