コード中のコメント(良いコメントと悪いコメントの違い)

2021/06/18 09:09

Henrik Warne
ストックホルムを拠点におくシニアソフトウェア開発者
この記事は、著者の許可を得て配信しています。
 On Comments in Code 

以前は、セルフドキュメント型のコードを書いていれば、コメントは必要ないと思っていました。しかし、私自身、実はコメントを書いていること、そしてそれが本当に役に立つことに気づいたのです。私がどれだけのコメントを書いているのか、そしてそれがどのようなものなのかを知るために、過去6年間のgitコミットを分析するスクリプトを書きました。その結果、コミットした行の7%にコメントが含まれていました。このブログ記事では、良いコメントと悪いコメントの違いや、スクリプトから得られた統計データについて詳しく説明しています。

Javadocはほとんど役に立たない

私がコメントに懐疑的だった理由のひとつは、Javadocスタイルのコメントが普及していることでした。このスタイルのコメントは他の言語にもあります。以下は、私が作ったばかりのPythonの例ですが、このスタイルでは代表的なものです。

これらのコメントの問題点は、全く情報を伝えられていないということです。多くの場合、メソッド名とパラメータ名をさらに数語で繰り返しているだけです。これらのコメントは、外部にエクスポーズされているAPIでは有用かもしれませんが、すべてのソースコードにアクセスできるアプリケーションでは、ほとんど役に立たないものです。そのメソッドの役割、パラメータの有効な入力範囲などが気になる場合は、コードを読んで確認したほうがよいでしょう。この種のコメントは、多くの価値を提供することなく、単に多くのスペースを占めているだけなのです。

コードのセルフドキュメンテーション

Javadocコメントを書く代わりに、メソッド名や変数名を最大限に利用した方が良いでしょう。それぞれの名前を使うことで、何のための計算なのか、それがどのように行われるのかを説明することができます。1つの大きなメソッドではなく、たくさんの小さなメソッドを書く良い理由の1つは、説明を含む名前を使用する場所が増えるからです。

コメントするとき

セルフドキュメント化されたコードを書けば、道のりは長くなります。しかし、より多くの情報があると便利な場合もあります。例えば、以下のコードにあるダイヤルゾーンの使用に関するコメントがそうです。

こちらにまた別の例を掲載しておきます。

『「何」ではなく「なぜ」をコメントしなさい』というアドバイスがされることがよくあります。これはおそらく私のコメントのほとんどでは網羅されていますが、私がコメントを書くタイミングについて考える方法ではありません。むしろ、ドメインや実装方法のいずれかにおいて、何か特別にややこしいことがあるときにコメントを書くことが多いです。

「コメントは必要ない派」(私もかつて所属していました)からの標準的なアドバイスは、コメントが不要になるようにコードを書き換えることです。しかし、これは常に可能であるとは限りません。ドメインがあまりにも複雑な場合もあります。また、コメントをつけるよりもコードを書き換える方が手間がかかる場合もあります。

また、コメントはコードと同期していないため、コードの理解を助けるどころか、妨げてしまうという難点もあります。

このようなことは時々起こりますが、私にとってはそこまで大きな問題ではありませんでした。私が分析したほとんどすべてのケースでは、コメントは有効でした。また、非常に便利なのでます。このような自分のコメントに出会うたびに、書いてよかったと思います。自分が解決しようとしている問題の詳細やニュアンスはすぐに忘れてしまいますし、コメントがあることでコンテキストや説明が追加されるのは素晴らしいことです。

コメントの記録

説明用のメッセージをログに記録していると、「無料で」コメントを得られることがあります。以下の例では、ログステートメントが何が起こったかを説明しているので、コメントは必要ありません。

コメント解析

最初に自分のコミットにどれだけのコメントが含まれているかを調べようと思ったとき、次のようなワンライナーですべてのPythonコミットのコメントを見つけることができれば十分だと思いました(私は#でしかコメントしません):

git log --author=Henrik -p|grep '^+[^+]'|grep '#' | wc -l

しかし、すぐにもっと詳しく知りたいと思うようになりました。行末のコメントと行全体のコメントを区別したかったのです。また、「コメントブロック」(連続した行のコメント)がいくつあるのかを調べたいと思いました。また、テストファイルは分析対象から外すことにしました。さらに、たまたまコメントアウトされたコードがあったとしても、それを確実に除外したい(残念ながらそのようなケースがいくつかありました)と思いました。最終的には、解析を行うためのpythonスクリプトを書きました。このスクリプトの入力は、「git log --author=Henrik -p」です。

出力結果を見ると、私が追加した17817行のうち、1299行にコメントが入っていました。行末のコメントが161件、1行のコメントが464件でした。最長のコメントブロックは11行で、3行以上の連続したコメントブロックが96件ありました。

まとめ

以前は、関数の名前をしっかり書けばコメントは必要ないと思っていました。しかし、実際にやってみると、私はコードの厄介な部分やわかりにくい部分にコメントをつける傾向があることに気がつきました。プログラムを読み返すたびに、苦労してコメントを付けておいてよかったと思いました。というのも、本当に便利だからです!

新着のコメント

appstore
googleplay
会員登録

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

  • 1.

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

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