コメントを書くということについて

コメントについて自分が考えることを書いていきます。

なぜコメントを書くのか？

まず、コメントを書く目的は、自分は以下の2点であると考えています。

• コードを書いた開発者がコードで表現できない情報を読み手に伝えるため

• 開発者が簡単にコードを理解して修正できるようにするため

1点目については、コメントがないとどういう目的で書かれたコードなのか、なぜその書き方を選んだのかということを理解できません。それによってコードの修正ができなくなってしまったり、修正によって想定していないバグを生み出してしまいます。

2点目については、コードが何をするものかがわかりづらいと、依存するコードを読んで再利用できるものか、副作用がないかを判断して修正、利用する必要が出てきてしまいます。

このようにコメントを書いて、暗黙的な知識を表出化し、コードを読みやすくすることで、システムの全体の複雑さを下げることができます。

なにをコメントとして書けばよいのか？

では、コメントを書くときにはどういった情報を書くべきでしょうか。 自分はコメントを書くときには、「コードに表せない情報」と「コードを読みやすくするための説明」を2つを書くようにしています。

コードに表せない情報とは、なぜこのコードを書いたか？なぜこのコードが必要なのか？という開発者の意図であったり、チームや組織の暗黙的なルールなどです。これらの情報を必要に応じてコメントとして残しておきます。

コードを読みやすくする情報とは、何をするコードなのか？、副作用のあるコードか？、修正する場合の影響範囲はどこか？などです。

良いコメントを書くためにはどうすればよいか？

コメントをなぜ書くのか？どんな情報を書くのか？について書いてきたので、最後はコメントをどうやって書くかについて書いていきたいと思います。

まず、コメントを読みやすいものにする方法としては、一貫性のあるコメントを書くことが大切です。JavaDocやJSDocなどテンプレートに沿ってコメントを書いたり、チームでコメントをどこに書くのか（interfaceなのか実装クラスなのか）どんな情報を書くのか、表記揺れのない用語を使うことなどを決めておくと読みやすいコメントを書くことができると思います。

また、コードを繰り返したコメントを書かないようにします。コードに出てくる単語をかいつまんだコメントを書いてしまうと、重要でない情報を持ったコメントになってしまいます。

外部モジュールの詳細については、外部モジュールの変更にコメントを対応させるのは大変なので、外部ドキュメントがある場合は、そのリンクをコメントとして残します。

コメントを書くためにはクラスやメソッドの抽象的な情報を理解する必要があるので、コメントを最初に書くことでシステムの設計を考えながらコードを書くことができます。後回しにしてしまうと、動くシステムに対してコメントをひたすら書く時間になってしまい、人によっては面白くない時間になってしまいます。

また、書いたコメントはコードレビューでチェックします。読み手がわかりづらいと感じたコードは、書いた人が後日読むときもわかりづらいものになっている可能性が高いので、レビューでコメントの書き方もチェックしてもらうようにしましょう。

ここまでコメントを書くことについて書いていきましたが、コードがシンプルな場合はもちろん無理して書く必要はありません。コメントを書きすぎてしまうとコードの表現力が貧弱になってしまい、重要な情報が埋もれてしまうからです。

最後に

コメントを書くときに、どういった目的で、どんな情報を、どういうことに気をつけながらコメントを書くか？ということをつらつら書いてみました。

コメントについては、「リーダブルコード」や「A Philosophy of Software Design」がとても勉強になるので、一読してみることをおすすめします。

リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック (Theory in practice)

A Philosophy of Software Design