はじめに
あなたは普段ソースコードにコメントを入れてますか？
コメントは正しく書けば、コードをより読みやすくすることができます。
読みやすいコードは、プロジェクトに加入した人が戦力になれるまでの時間を短縮できたり。
引き継ぐ際にスムーズになったり。
後から読んで頭を抱えずに済んだりと、たくさんいいことがあります！
なので今回は「何をコメントするのが良いのか」について記載しました。(コメント自体の書き方 種類などには触れません)
コメントの目的
私もそうでしたが、コメントの目的は「コードを説明する」ことと思っている人がいると思います。
それも間違いではないのですが、具体的に言うと「書き手の意図を読む人へ伝える」ことです。
具体的にどんなコメントをしたらいいのか
コードを書いている時の自分の考えを記録する。
読み手の気持ちになって何が必要かを考えて書く
過剰なコメントは避ける
コードを書いている時の自分の考えを記録する。
コードを書くときは、何かしら考えながら書いていると思います。
書いているときは、頭の中に考えがあるのですぐ理解ができますが、読む人はコードでしか情報が得られません。
後から読む自分の為、引き継ぐ人の為にも考えをコメントとして記録しましょう。
具体例①
//○○を使うよりxxの方が△△％早かった。
自分で試した結果どうなったかが分かるようになっています。これが無ければ別の人が別のやり方に変えて無駄な時間が発生したかもしれません。
具体例②
//ソースが汚くなってきたので、そろそろ整理した方がいい
//○○を別クラスにするといい
時間が無いときにかかれることが多いと思います。
汚くなっていること、その改善策が書かれているので改修しやすいです。
この場合、コメントの頭にTODOとつける人もいると思います。
具体例③
//この方法では極稀に○○が生じるが、パフォーマンスを優先した
何か理由があって、問題を残している場合もあると思います。
そんな時にコメントが無いと、別の人が改善策を探したり、試験したりと時間が無駄になってしまいます。
読み手の気持ちになって考える
誰でも人のソースを読むことは誰でもあると思います。
読んでいると「なんでこんな処理になっているんだ？」と疑問に思ったことないでしょうか？
そんな疑問を先読みして、コメントをすると読む人の理解速度が上がるでしょう。
何を意識をすればいいか
Why:なぜこのコードを書いたのか
What:何がしたいか
bad know-how:何かの訳があってこのコードになっているかを説明
読み手からしたらWhyがあると理解がしやすいです。
Whatはコードを読むと分かることもあるのでWhyより重要度は低いでしょう。
bad know-howは先ほどの具体例③がまさにそれですね。これも重要でしょう。
過剰なコメントは避ける
簡単なコードにコメントをしたり、コメント自体の量がかなり多くなってしまったりすることがあります。
無意識にコメントをガリガリ書かずに、一度読んで正しいか確認しましょう。
具体例①
//画面にHello Worldと出力
printf("Hello World");
実行するだけですぐ分かると思います。
printfが分からなくても調べれば簡単に解決する問題なので、この場合のコメントは過剰です。
具体例②
//text文字列を指定した色をつけて出力する
void Output(string text, Color color)
これは関数名と引数だけで大体何がしたいか分かると思います。
名前だけで十分説明されているものに対して、コメントを打ち込むのは過剰です。
このコードにコメントをつけるなら、どこに出力するかや、引数の扱いで注意したほうがいいことなど
名前だけで把握できない新しい情報を与えるのが良いとされます。
まずはHow(どうやってプログラムを動かすか)を書かないことを意識してみましょう。
おまけ
先ほどTODOというのを使いましたが、これは「後で手をつける」という意味になります。
他にも
FIXME:コードに問題がある
HACK:コードを改善する必要あり
XXX:危険
などがあります。
上のワードを全検索をかけたら問題がある箇所がすぐ分かるので、修正しやすいです。
visual studioではタスク管理というものがあり、TODOと書くとタスク一覧から見れたりします。
まとめ
コメントは書き手の意図を読む人へ伝えることです。
コードを打っている時の考えを記録し、読み手の立場で読んでみる。
コード上で語っていることは書かない。
これ意識するだけで、読みやすいコードになるでしょう。
しかし、コメントが完璧でもコードが読みにくいと意味がありません。
コメントも大事ですが、分かりにくそうだと思ったらまずはコードの命名や組み方の見直しをしてみましょう。
というわけで次回は読みやすいソースについて書こうと思います。