役に立つコードコメントと役立たないコードコメント

2021/06/24 08:20

Jim Nielsen
SageSureのデザインおよびUIアーキテクチャのディレクター
この記事は、著者の許可を得て配信しています。
Useful and Useless Code Comments

私は最近John Ousterhout氏のA Philosophy of Software Design.を読んでいます。

この本の中で、コードのコメントについてこんなアドバイスがありました。

残念ながら、コメントの多くはほぼ役に立っていません。それはなぜかという理由は、コメントがコードを何度も繰り返している点にあります。コメントの中の情報の全てがコメントの横にあるコードから簡単に推測されてしまうからです。

そして、彼が言っていることを説明するために、例を挙げています。

// Add a horizontal scroll bar
hScrollBar = new JScrollBar(scrollBar, HORIZONTAL);
add(hScrollBar, BorderLayout.SOUTH);

// Add a vertical scroll bar
vScrollBar = new JScrollBar(JScrollBar.VERTICAL);
add(vScrollBar, BorderLayout.EAST);

// Initialize the caret-position related values
caretX = 0;
caretY = 0;
caretMemX = null;

このようなコメントに対する議論は、コード自体と「同じレベルの詳しさ」であるという点にあります。コードはその意図が明確なので、コメントは余計なものでしかないのです。

John氏はさらに、コメントを有効なものにするためには、コードからは推測できないレベルの情報を提供する必要があると述べています。

コメントは、それと詳細さが異なる情報を提供することで、コードを補足するものです。コードよりもより詳しい情報を提供してくれるコメントもあります。こういったコメントは、コードの正確な意味を明らかにしてくれます。またコードよりもより抽象的なレベルの情報を提供してくれるコメントもあります。そういったコメントは、コードの背後にある理由などの直感や、コードについてのよりシンプルでより抽象的な考え方のような直感的な情報を提供してくれます。

このように、どうすればコードのコメントを役に立つものになるのか、もしくはそうではなくなるかについては、非常に公平で合理的な説明ができると思います。

しかし、私にはこれに対して意見があります。

もし誰かがコメントは何の価値も生まないと言ったら、私は「それは誰にとってなのか?」と聞くでしょう。

個人的には、分かりやすいコメントを書くのは悪いことだという考えは好きではありません。

コードと同じレベルに詳しいコメントは、コードを流暢に読んだり書いたりするあなたにとっては役に立たないかもしれませんが、私のようにコードの読み方や書き方をまだ理解していない者にとっては役に立つものです。私がコードを書くときに便利だと思うのは、自分の意図を(平易な言葉で)述べ、それをコードに翻訳し、記述を比較して自分の目的がどれだけ達成されたかを確認できるからです。

もちろん、チームで協力している場合は、一緒にコードを書く方法を考えなければなりません。そのためには妥協して、自分にとっては役に立つが他の人にとっては邪魔なだけのコメントをカットする必要があるかもしれません(コードをオーサリングするプロセスの最後には常にそうしてもいいかもしれません)

これが分かりやすい記述かもしれませんが、もし「役に立たない」コードコメントを書くことがあなたの役に立つのであれば、それは役に立たないものではありません。実はその逆なのです。つまり、役に立つということです。

私がスペイン語を学んだ時のことを思い出します。いつも、「頭の中で単語ごとに翻訳していってはいけない。そうではなく、自然な言葉で言葉の意味を理解しなさい」と言われます。しかし、私が初めてスペイン語を学んだときは、まさに常に頭の中で翻訳していました。

  • スペイン語のフレーズを聞く
    「¿Como te llamas?」(※スペイン語で「あなたの名前は何?」の意味)
  • 頭の中でそのフレーズを自分の母語に翻訳する
    「あなたの名前は?」
  • 頭の中で自分の母語での返事を考える
    「私の名前はJimです」
  • このフレーズを頭の中でスペイン語に翻訳する
    「Me llamo Jim」(※スペイン語で「私はJimと言います」の意味)
  • 声に出してそのフレーズを繰り返す

最終的には、頭の中で段階的に行ごとに翻訳する必要がないほど私はスペイン語が流暢になりました。言葉はそれぞれの言語でそれぞれの意味を持っているのです。この時点で、私は頭の中で英語に翻訳することは(私にとって)無駄であることに気づきました。

この例をもう少し掘り下げて、これをコードと仮定して考察を深めましょう。

// What is your name?
¿Como te llamas?

// My name is Jim
Me llamo Jim.

// Where is the library?
¿Donde esta la biblioteca?

コードのコメントについてみんなの意見を聞いていると、このようなコメントは役に立たないと思うかもしれません。John氏の本には次のように書かれています。

コードを見たことのない人が、コメントの横にあるコードを見ただけで、そのコメントを書くことができるでしょうか?もしその答えがイエスであれば、そのコメントはコードを理解しやすくするものではありません。

そのコメントは、コードを理解しやすくするのに役立つのでしょうか?それは、その質問を誰に聞くかによります。

コードのコメントが役に立たないというのは、コードを流暢に読んでいる私たちが判断したことです。コードを読んだり書いたりしている自分よりも流暢でない人にとってのコメントの価値を無視しています。

「自分はある言語に流暢ではない」と思っている人は、他の人が「役に立たない」、「明白だ」、「冗長だ」としているコメントから多くの価値を得られるかもしれません。というのは、自分があまり慣れていない言語(例えば母語以外の外国語)を自分の母語に翻訳するのを助けてくれるからです。

また、コメントは、読まれるときと書かれるときでは、その目的が大きく異なります。その二つは、全く異なる種類の活動なのです。

だから、あるスタイルのコードコメントが役に立たないと言われたら、「誰にとって役に立たないのか?」と自問してみてください。もちろん、チームの役に立つコードに対しては気を配らなければなりませんが、特に個人のプロジェクトでは、ある種のコードコメントが有用であれば、それで問題ありません。

appstore
googleplay
会員登録

会員登録して、もっと便利に利用しよう

  • 1.

    記事をストックできる
    気になる記事をピックして、いつでも読み返すことができます。
  • 2.

    新着ニュースをカスタマイズできます
    好きなニュースフィードをフォローすると、新着ニュースが受け取れます。