エンジニアのバイブル「リーダブルコード」読んでみた 五章
リーダブルコードの五章を読み終えたのでまとめです。
五章「コメントすべきことを知る」
コメントの目的は、書き手の意図を読み手に知らせることである。
コメントについて大事な考え方が以下の三つになります。
コードからわかる場合コメントしない。
考えをコメントする。
全体像のためにコメントする。
まずコメントはなぜするかというと「コードリーディングの時間を減らす」が一番の理由だと思います。
ですがコメントをするということは純粋に読むべき行数が増えることになるのでむやみやたらにコメントをすると見にくくなってしまいますよね。
なので基本的にはコメントはすべきで無いです。
コメントする場面としては関数名や、変数名を説明として書かれることが多いと思われます。
このようなパターンではコメントを書かざるを得ない場合もありますが、一番の対策としては関数や変数の名前を変更することが一番です。
（変更後の名前は2.3章を参考に）
ただわかりやすくしたとしても簡単に理解できないコードは存在します。
理解に難しいコードの例としては実装方法が複数パターン存在している場合です。その場合はなぜこのような実装をしたか、実装当時の考え方をコメントすることによって読み手の思考時間を大幅に減らすことが出来ます。
他にもstep数が多いコードも全体を把握するためにコメントをブロックに分けて記載するとより読み手に優しくなります。
またコメントする際に以下のようにコメントを付けるとより見やすくなります。
{
// TODO: もっと早いアルゴリズムを使う
}TODO:あとで手をつける
FIXME:既知の不具合があるコード
HACK:あまり綺麗じゃない解決策
XXX:危険!大きな問題がある
あくまでここからは個人の考え方ですが、実装したコードを対面でレビューする想定をして見てください。
その場合にどのように説明するかを簡単に考えるとコメントすべき部分、修正すべき名前などが出てくると私は考えています。
以上！！
コメントを書かないでいいような綺麗なコードを実装しよう