はじめに
最近、ソースコード中に書くコメントについて他のエンジニアと話すことがあって、僕がコメントを書くときに考えてること、その役割を考えてみました。
この記事は考えたことを書き起こしたものです。
そもそもコメントは何のために書くのか
コメントについて僕が大学生のころに
- コメントはなるべく書いたほうが良い
- そもそもコメントがなくてもわかるコードにするべきだ
などを聞いたことがありました。（そんな気がする）
上記の例や他の意見などでも、結局何を目的としてコメントを書くのかを考えると、
「次にそのソースコードを触るエンジニアに対して、伝えなければいけないことを伝えたい」
がためにコメントを書きます。
言ってしまえば、伝言ゲームみたいな感じです。
自分が伝えたいことが次のエンジニアに伝わらないのであれば、そのコメントは意味をなしませんし、誤って伝わってしまうのであれば、そのコメントを改善する必要があります。
自分の伝えたいことを次にそのソースコードを触るエンジニアへ正しく伝え、助けることがコメントの役割です。
どんなことを伝えると良いのか
では、どんなことを伝えると良いのでしょうか。
こういうコメントは書く必要がないなどの個別な事象についてはその状況やソースコードによって変わると思うので、僕がコメントを書くときにどんなものにはコメントを書くように意識しているのかをざっくりまとめました。
役割、振る舞いについて
関数や変数が何のために存在しているか、どんな役割があるのか、どんな振る舞いをするものなのかについて書きます。
もちろん、ソースコードを読んですぐわかるもの（役割、振る舞いが明らかなもの）には書く必要はありません。
意図したものなのかどうかについて
その実装は意図したものなのかどうなのかについて書きます。
バグなのか、仕様なのかは次に読むエンジニアはわかりません。わかるのはソースコードを書いた本人だけです。
直感的ではないものについて
これはソースコードが簡潔でない場合のことではなく、振る舞い、出力などが直感的なものとは反しているときを指してます。
他のエンジニア（もしくは自分）がそのソースコードを読んで、「予想してたのと違うな」と思うものに対して書きます。
さいごに
コメントの役割、どんなことを書くべきかについて書きました。
まだ、3年目の若手エンジニアなのでコメントを書く歴が長いわけではないですが、お役に立てたら嬉しいです。
また、こんなときにコメントを書くようにしてるよなどあれば、コメントや編集リクエストで教えていただけると幸いです。