Ch.5~6（コメントすべきことを知る＆コメントは正確で簡潔に）｜『リーダブルコード』読解メモ #3
コーディングにあたっての指針を示しておければということで、『リーダブルコード』を課題本に設定しまとめています。（基本的に本を片手にご確認いただく前提なので、細かいところの記述は省略すると思います。勝手に解釈した上での要約なので、万が一解釈違いは生じていたとしたらご容赦ください。）
#1ではCh.1の『理解しやすいコード』とCh.2の『名前に情報を詰め込む』について、#2ではCh.3の『誤解されない名前』とCh.4の『美しさ』についてまとめました。
Ch.1~2（理解しやすいコード＆名前に情報を詰め込む）｜『リーダブルコード』読解メモ #1 - lib-arts’s diary
Ch.3~4（誤解されない名前＆美しさ）｜『リーダブルコード』読解メモ #2 - lib-arts’s diary
#3では引き続いて、Ch.5の『コメントすべきことを知る』とCh.6の『コメントは正確で簡潔に』についてまとめていきます。
以下目次になります。
1. Ch.5_コメントすべきことを知る
2. Ch.6_コメントは正確で簡潔に
3. まとめ
1. Ch.5_コメントすべきことを知る（簡単な要約）
Ch.5の目標はコメントすべきことを知ることだ。コメントの目的は「コードの動作を説明する」ことだと考えがちだが、それはごく一部でしかない。コメントの目的は、「書き手の意図を読み手に知らせること」であると考えておくと良い。
コードを書いているときは頭の中に重要な情報がたくさんあるが、誰かが書かれたコードを読む際にはその情報は失われてしまうということは注意しておかなければならない。コードを読む人が持っているのは目の前にあるコードしかない。Ch.5では頭の中にある情報をいつ書き出せば良いのかについて触れる。具体的には以下の話題を取り上げる。
・コメントするべきではないことを知る
・コードを書いている時の自分の考えを記録する
・読み手の立場になって何が必要になるかを考える。
以下、上記について詳しく見ていく。
・コメントするべきではないことを知る
まず、コメントを読むことでその分だけコードを読む時間がなくなることに注意が必要である。そのため、OOクラスの定義やxxコンストラクタの定義など、コードからすぐにわかることはコメントに書かないようにすべきである。
また、コメントよりも名前にこだわるようにしたほうがよく、コメントが長くなる際は名前に意味をもっと持たせられないか検討する方が良い。
・コードを書いている時の自分の考えを記録する
優れたコメントというものは「考えを記録する」ためにあると考えておくと良い。下記にいくつかの観点をまとめる。
- 「監督のコメンタリー」を入れる
-> 作品がどのように作られたのかのイメージがつくような「映画のコメンタリー」のイメージを持つと良い。例えば"当データにおいてはハッシュテーブルよりもバイナリツリーの方が40％速かった。"など、コメントから情報が得られるようにしておくと良い。また、リファクタリングが必要と思われる際は、リファクタリングを示唆するようなコメントを残しておく方が、読む側の役に立つ。- コードの欠陥にコメントをつける
-> コードは絶えず変更されているので、その過程で欠陥が生じる可能性がある。その欠陥については、文書化をなるべく行うようにすると良い。例えば「もっと高速なアルゴリズムを用いる」などである。この際にTODO(後で手をつける)、FIXME(既知の不具合がある)、HACK(あまり綺麗じゃない解決策)、XXX(危険、大きな問題がある)などはよく使われるので抑えておくと良い。- 定数にコメントをつける
-> 定数を定義する際にはその定数が何をするのか、なぜその値を持っているのかという「背景」が存在する場合が多いので、注意しておくと良い。
・読み手の立場になって考える
他の人にコードがどのように見えるかは常に意識しておくとよく、この際に「他の人」はプロジェクトのことを自分のように熟知していないことは注意が必要である。どこにコメントをつけるかを判断するにはこのような考え方を持っておくと良い。
そのため、質問されそうなことを想像する、ハマりそうな罠を告知する、「全体像」をコメントする、要約コメントを残すなどは意識しておくとよい。
2. Ch.6_コメントは正確で簡潔に（簡単な要約）
Ch.5では何をコメントに書くべきかを説明したが、Ch.6ではどうすればコメントを正確で簡潔に書けるかを説明する。コメントを書くのであれば正確に書くべきであるのに加え、簡潔に書く必要がある。「コメントを書くにあたっては領域に対する情報の比率が高い必要がある」ことに意識する必要がある。
以下その具体的なやり方を見ていく。
・コメントを簡潔にしておく
-> 1行で説明できる内容は1行で説明するようにするべき。・曖昧な代名詞を避ける
-> 「その」など代名詞はなるべく対象を用いて記述すると良い。・歯切れの悪い文章を磨く
-> "優先度を変える"ではなく"優先度を高くする"のように、直接的な言葉を使うようにすると良い。・関数の動作を正確に記述する
-> "行数を数える"ではなく、"改行文字('\n')"を数えるのように、関数の動作を正確に記述するようにすると良い。・入出力のコーナーケースに実例を使う
-> 関数の入出力には極力関数の処理を反映できる実例を用いて説明しておくと良い。・コードの意図を書く
-> "値段の高い順に表示する"のようにプログラムの動作を高レベルから説明するコメントをつけるようにすると良い。・「名前付き引数」コメント
-> 引数を名前付きで渡すことによって関数に与える引数の情報を明示化することができる。Pythonなどではデフォルトでできるが、できない言語でもインライコメントを使うなどで同様な記述にすることもできる。・情報密度の高い言葉を使う
-> 「ヒューリスティック」のような多くの意味を含んだ言葉や表現が数多く存在するため、こうした表現を極力使うように心がけておくと良い。
3. まとめ
#3ではCh.5の『コメントすべきことを知る』とCh.6の『コメントは正確で簡潔に』について取り扱いました。どちらもコメントについての内容でしたが、いかに文量を少なくわかりやすくするかについて様々な観点からまとまっていたので、非常に有意義な内容でした。
#4ではCh.7の『制御フローを読みやすくする』とCh.8の『巨大な式を分割する』についてまとめていきます。
