コードを読む人の助けになるコメントを書くために

  • 40
    いいね
  • 0
    コメント

コメントを書かなくても理解できるコードは簡潔で美しいです。

しかし現実には、ライブラリのバグ対応や緊急リリースで時間が限られているなどで、その場しのぎのコードや応急処置的なコードを書かざるを得ないことがあります。

そのようなコードに何もコメントがないと、他の人や後から自分が見たときにそのコードの意図を汲み取ることが難しくなります。

場合によっては、リファクタリングの際に不必要なものとして削除されプログラムがリグレッションする可能性もあります。

そのようなことを防ぐために普段気をつけていることを紹介します。

「普通はこう書く」から逸脱するコードはなぜそれをするのか理由を書く

使用しているライブラリやSDKにバグがあって「普通はこう書く」というコードを書いても期待どおりに動かないことがあります。

そういうときは、一見すると稚拙で場当たり的に見えるコードを書かなければならないこともあると思います。

そのコードだけを他の人が見ると、単純に実力不足でそのような書き方になっているという誤解を与えかねません。

したがって意図してそのように書いていることをコメントで明示します。

「何をしているか」はコードからわかりますが「なぜそうしているか」はコードからはわからないので理由を書いておくことは重要です 1

// xxxライブラリのバグにより期待するxxxの値が返ってこないためxxxする

参考にした記事のURLを書く

URLを書いておくメリットは多いです。

  • がんばってコメントをたくさん書くよりも参考にした記事を紹介した方が情報量が多いことがある
  • URLを書くだけなので楽
  • 文字だけでは表せない図やイラストを示せる
  • 問題の背景や他の解決方法などのより詳しい議論を知れる

以上のような理由から、参考にした記事がある場合はできるだけそのURLを書くようにしています。

URLと合わせて簡単なコメントも書いておくほうが親切だと思いますが、それすら面倒くさいとき・時間がないときはURLだけでも書いておくと良いです。少しでも情報があるのとないのとでは雲泥の差があります。

// xxxの挙動については http://stackoverflow.com/questions/xxx を参照のこと

うまくいかなかった方法を書く

試行錯誤を重ねた箇所には失敗したやり方も書いておくようにしています。

あとで誰かがリファクタリングするときに「もっといい書き方がある」といって、もうすでに試した失敗する方法へ書き直してしまうのを防ぎます。

悩んだ跡を残すことで他の人に同じ轍を踏ませないようにすることができます。

うまくいかない方法を試しているときにエラーログが出た場合はそれをコピペしておくのがおすすめです。エラーログをそのままググれば情報が見つかることが多いのでどのようなエラーなのか詳しく知ることができます。エラーログは簡単に書いておける割には表せる情報量が多いです。

// xxxという方法を取ったところ「Error: xxx xxx」というエラーが出た

さいごに

僕自身、何かにハマってある程度の時間を掛けて解決方法を調べた場所には上記のようなコメントを残すようにしています。

迷った痕跡を残しておくと他人にとっても将来の自分にとってもとても役に立ちますし、実際にこのようなコメントを書いておいて良かったと思ったことが何度もありました。

ぜひ参考にしてみてください。

明日は @aokis さんのポケモン話です!



  1. リーダブルコード にそんなことが書いてありました