# 目次
# はじめに
以下の記事は，オライリージャパン社から出版された
『プログラマが知るべき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
16. コメントについてのコメント カル・エヴァンス (Cal Evans)：『プログラマが知るべき97のこと』
私が大学に入ったばかりの頃の話です．
プログラミングの授業の１時限目，
先生からBASICのコーディングシートが２枚配られ，
黒板には
「ボウリングのスコアを10個入力し，
平均を計算するプログラムを書け」，
と指示が書かれていました．
それだけ書くと，
先生は教室を出て行ってしまいました．
そんなに難しい課題ではありません．．
最終的にどんなコードを書いたかは忘れてしまいましたが，
FOR/NEXTループを使って書いて，
全部で15行あるかないかだったと思います．
若い人は「コーディングシート」と言われても
わからないかもしれません．
昔は，まずコードを紙に手で書いてから
コンピュータに入力していたのです．
（一回で入力できる量は70行くらいに制限されていました．）
その時は，どうしてシートを二枚渡されたのかわからずに
戸惑ったのを覚えています．
よくわからないので，一枚目に下書きをして，
二枚目に清書することにしました．
（私は字が恐ろしくきたないのです．）
きれいに書けているということで少しは評価も上がるかな，
と期待もしていました．
次の授業のはじめに課題が返ってきたのですが，
見て驚きました．
合格点ぎりぎりの評価だったのです．
（後から思うと，それは私の大学生活を暗示していたのかもしれません）
そして，私がせっかくきれいに書いたコードの上には，
こう走り書きしてありました．
「コメントは入れないのですか？」
そのコードがどういうもので？
どういう目的で書いたものなのかは，
もちろん先生と私にはよくわかっていました．
しかし，その二人だけがわかればいい，
というものではなかったのです．
その課題で私が学んだのは
「コードは，次に見る人がすぐに理解できるように書く」
ということでした．
これは今後も決して忘れることはないでしょう．
コメントは悪ではありません．
有用なものです．
そして分岐やループなどと同様，
プログラミングには必須の要素といえます．
ある程度以上新しいプログラミング言語には，
一定の形式で書かれたコメントを基に，
自動的にAPIドキュメントを作成するツール（例：javadoc)）
などが用意されています．
まずはじめにこういうツールを利用するのが良いでしょう．
しかし，それだけではまだ十分だとは言えません．
プログラムのコードには，
「このコードはどういう目的で書かれたものなのか」
の説明をするコメントを入れるべきなのです．
「書くのに苦労したコードは，読むのにも苦労する」
という格言がありますが，
読むのに苦労するようなコードを，
コメントもつけずに放置すれば，，
顧客にも，
自分の働く会社にも，
同僚にも，
そして将来の自分にも害を及ぼすことになります．
ただし，コメントは多く入れればいいというものではありません．
コメントを入れるのは，
あくまでもコードをわかりやすくするためです．
コメントを入れたことで,
かえってコードがわかりにくくなっては意味がないのです．
必要にして十分な量のコメントを，
適切な場所に入れること．
「このコードで何がしたいのか」，
を読む人にわかってもらうこと，
それが重要です．
まず，ヘッダコメントには
「プログラマがコード本体をまったく読まなくても
利用することはできる」
というぐらいの情報を盛り込みます．
そしてインラインコメントには，
自分の次にコードを見て
修正や拡張する人の助けとなるような情報を
適宜盛り込みましょう．
ずいぶん前ですが，こんなことがありました．
そのとき，私は上の人間に腹を立てていました．
あるコードに関して，彼らが採用を決めた設計が
どうしても良いと思えなかったからです．
若いプログラマにはありがちなことです．
その設計を使用せよ，
ということはメールで指示されたのですが，
私は怒りのあまり，
そのメールの文面をコードのヘッダコメントに
コピペしてしまいました．
そしてその後になって，
そのコードをコミットした後にレビューするのは，
まさにそのメールを送ってきた上司である，
ということがわかったのです．
その時初めて，
CLM(Career-Limiting Move:出世の妨げとなるような行動）
という言葉の意味を，
実感に伴って理解できたのでした．
■著者データ
[カル・エヴァンス (Cal Evans)]
IbuildingsのPCE担当ディレクタを務める．
プログラマとしては，
すでに２５年の経験を積んでおり，
使用してきたプログラミング言語は多数に上る．
またいくつもの言語の様々なトピックに関して，
雑誌への寄稿，書籍の執筆もしている．
国籍は米国だが，現在はオランダのユトレヒトに住み，
講演，執筆などを行うほか，
グローバルなPHPコミュニティの活動にも参加している．
ブログも参照のこと．
関連記事
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
MyEnigma Supporters
もしこの記事が参考になり、
ブログをサポートしたいと思われた方は、
こちらからよろしくお願いします。
