コメントによって可読性をあげることを考えてみる

投稿者 投稿日:

コメントするポイント

コメントというのはコードどを読むうえで理解しやすく、

わからない事を補完してくれるありがたい存在です。

しかしながら、コメントないほうが可読性が上がって読みやすいと感じることもあります。

ではコメントする/しないの判断はどうするか。

私がコメントをするとき、以下の２点を意識しています。

  • 理由を含むコメントでコードを補完する
  • コードでわかることはコメントしない

コードの得意なものは「How」「What」逆に「Why」は苦手

昔は究極のコードというのはコメントなどなく、純粋なコードだけで構成されると考えたりもしました。

ただ、コードが表現できる内容にも得意不得意があることに気が付きます。

得意とするのは5W1HでいうとこのHowとWhatです。

プログラムというのは何か目的があって作られていて、コードとはどのように目的を達成するかが書かれているものです。

つまり、コードとはHowとWhatそのものと私は考えています。

逆に苦手なものとしてWhyがあります。

コメントというのはコードで表現できないこの「Why」を記載すると価値が高まります。

手段（How）だけのコメントはいらない場面が多い

さて、コードが得意とするHow、Whatについての説明は以上になります。

それでは具体的なコードサンプルでHowとコメントの関係を見ていきます。

try {
  someMethod();
} catch (exception exception){
  //ログを残す
  logger.info("エラー発生しました .etc")
}

「logger.info」という記述はデファクトスタンダード的にログを残す表現です。

つまりエンジニアは「logger.info」という記述を見たときに「ログを残しているんだ」と認識します。

つまり上記例は、エラー発生時に「ログを残す」そして「ログを残す」というように読めます。

こうなるとコメントとコードがやっていることが一緒になってしまいコメント価値が薄れます。

むしろ、コードのほうが具体的なエラーメッセージを表現している分、内容が濃いです。

理由（Why）が含まれるコメント

以下のサンプルがパフォーマンスの関係上ログを残さないのが原則の処理だったとします。

try {
  someMethod();
} catch (exception exception){
  //バグ調査のため、ログを残す
  logger.info("エラー発生しました .etc")
}

であれば、ログを残しているような記述があれば、改修の際に消される可能性があります。

ですが、そこに理由が記載されていればどうでしょうか。

「バグ調査のため、ログを残す」であれば、理由があります。

また、課題が解決したときに消されるであろうことが、理由を含んでいるため推測もできます。

Howをコメントとして残してよいパターン

同じ「ログを残す」を書く場面も状況によってはあり得ます。

例えば、古いコードなどでよくある名前がコード体系でできているなど何をしているのかわからない状況です。

try {
  someMethod();
} catch (exception exception){
  //ログを残す
  mm03a01.action("エラー発生しました .etc")
}

「mm03a01.action」が一体何をしているのかがわかりません。

この場合は「ログを残す」というコメントが威力を発揮します。

記述されているコード処理と内容が乖離しているときもコメントの出番ですね。

得意としているはずのHow、Whatが読み取れないのですから。

そうした時もコメントしてあげるとよいでしょう。

まとめ

最後にまとめです。

コードで表せない部分をコメントにしてコードでわかることはコメントしないというシンプルな内容になっています。

  • 理由を含むコメントでコードを補完する
  • コードでわかることはコメントしない

コメントでコードの可読性が上がるのか？

引き続き考えていきたいと思います。

投稿者: nry