自分が「プログラマが知るべき９７のこと」のエッセイを読んで、気づきと学びがあったなと思ったことの「その３」です。
今回のポイント
プログラミングをテーマにしたエッセイ集です。
xn--97-273ae6a4irb6e2hsoiozc2g4b8082p.com
97のこと・・と言いながら、107個ものエッセイがあります。
それなりのレベルの開発者のエッセイ集なので、読むと色々と勉強になります。
今回は、自分が勉強になったこと「その３」として
コメントはコードに書けないことを最低限に書く
にというキーワードでポイントを引用しながら書こうかなと思います。
ノイズになるようなコメントは書かない
ソースコードにコメントを書くのは「良いこと」と教えられました。
コメントをたくさん書いていることを自慢する人にも一杯会いました。
でも、エッセイにある。
コードに何か価値を加えるわけでもない、そういうコメントは、一種の「ノイズ」とみなすことができます。
という意見に、自分はもろ手をあげて賛成です。
なぜかというと、他人の書いたソースコードの以下のようなコメントにイライラした経験を腐るほどしてきたからです。
プログラミング言語で一度書いたことを、もう一度自然言語で言ったからといって、正しさが増すなどということはありません。
コメントの部分は、実行されるわけではないので、ノイズのようなコメントは、コードを読む時にも実行する時にも、まったく役に立たないわけです。
また、コメントの内容は、あっという間に陳腐化するという点、にも注意が必要です。
たとえば、コートがとのバージョンなのかを知らせるコメントや、「どのバージョンでどういう修正を加えたか」という属鹿を入れてコメントアウトされたコードなどがよくありますが、そのような情報はバージョン管理システムを使えば、はるかに合理的に得ることができます。
だから。
以下のようにしなさいという提言は正しいと思います。
本来コードを見ればわかるはずのことをコメントに書かなくてはならないのは、コードの構造や書き方を見直す必要があるということです。
メソッドやクラスの名前がわかりにくいからコメントを書くというのなら、名前を変えてしまった方がいいでしょう。
関数が長くて分かりにくいせいでコメントが要るのなら、関数を小さく分割して、どういう関数かがすぐに分かる名前を個々につける方がいいでしょう。
コード自身にできる限り「語らせる」ようにするのです。
どうしてもコードに語らせることが不可能な時に、語らせたかったものとコードとのギャップこそコメントに書くのです。
コードに「書いていないこと」ではなく、コードに「書けないこと」のみをコメントにするのです。
ボリュームのあるヘッダコメントは願い下げです
このエッセイ集は、いろんな人が各々の考えで書いているので、たまに、真反対の意見じゃないかと思うエッセイも混じっています。
たとえば、コメントについても、こんな内容のエッセイもあります。
必要にして十分な量のコメントを、適切な場所に入れること。
「このコードで何がしたいのか」を読む人にわかってもらうこと、それが大事です。
まずヘッダコメントには「プログラマがコード本体をまったく読まなくても利用することはできる」というくらいの情報を盛り込みます。
そしてインラインコメントには、自分の次にコードを見て修正や拡張をする人の助けとなるような情報を適宜(てきぎ)盛り込みましょう。
これは、以前から教えられてきた内容に近いです。
なので、前段の「コードに書けないことのみをコメントする」という方針とは方向性がずれます。
これも正論なのですが。
ヘッダコメントには「プログラマがコード本体をまったく読まなくても利用することはできる」というくらいの情報を盛り込みます。
の部分は個人的には同意できません。
なぜかというと。
長すぎるヘッダコメントは疲れる。
これが自分の本音だからです。
プログラムを利用するための情報はコメントではなく「テストコード」で提供してほしいと、個人的には思います。
別記事にあるような。
良いテストはドキュメントのようなはたらきをします。
テスト対象となるコードについて知るのに役立つのです。
「このコードはどう動くのか」を教えてくれるのが良いテストです。
こういう「良いテスト」を提供して、それで伝えきれない部分だけコメントにしてもらう・・のが、いいです。
コメントはテストされないし、不正確であってもわからない
経験的に。
何回もメンテナンスされているソースコードって、ソースコードとコメントの同期がとれていなくて混乱を招くことがよくあります。
まさに。
「コメントに全部書いてあるから大丈夫」という人もいるかもしれません。
しかし問題は「実行されるのはコメントではない」ことです。
やはりコメントも他の種類の文書と同様に、誤ったことが書かれている恐れがあります。
なんですね。
今や、IDEは進化しているので、プログラムコードのミスは自動チェックツールが見つけてくれます。
でも、コメントは人間が自力でチェックしないといけません。
大量のコメントが書かれたソースコードのバグ修正をするときに、じっくりコメントを全部見直して正しく修正する時間は普通とれません。
とりあえず、トラブル回避が最優先。
コメントは後でなおそう・・で終わります。
でも、その「後」は経験上、永遠に来ることはありません（笑）
やはり
「このコードはコメントがなければわかりにくい」と感じたのなら、コメントを書くよりも、リファクタリングすることを検討した方がいいでしょう。
・・・
コードに何か変更を加えて、その変更の内容について説明したい場合にも、コメントに書くのではなく、バージョン管理システムへのチェックインの際に添えるメッセージに書くべきでしょう。
というのが正解でしょうね。
とにかく。
- コードを利用するための情報は「テストコード」として書く。
- コメントは「コードに書けないことを最低限に書く」。
この２点が得に意識しないといけないというのが、このエッセイ集で学んで、自分なりに消化した結論です。
ではでは。