こんばんは。マル太です。
前回は、リーダブルコードの第5章「コメントすべきことを知る」についてまとめました。
今回は、第6章「コメントは正確に、簡潔に」について、まとめます。
正確で簡潔なコメントを書くことの重要性
第5章では、「どんな時にコメントを書くべきか」 を学ぶことができました。
今回は、「どのようにコメントを書けば良いのか」に焦点を当てて考えていきます。
コメントは、コードの理解を助けるためのものです。
しかし、コメントが不正確だったり、冗長だったりすると、かえってコードの理解を妨げてしまう可能性があります。
そのため、コメントは「正確かつ簡潔に書く」ことが重要です。
正確なコメントを書くためのポイント
1.事実と異なるコメントは書かない
・コードの変更に合わせて、コメントも必ず更新しましょう。
・古くなったコメントは、誤解を招くだけでなく、バグの原因にもなります。
2.あいまいな代名詞を使わない
・「それ」「これ」「あれ」などの代名詞は、何を指しているのか分かりにくい場合があります。
・代名詞を使う場合は、具体的に何を指しているのかを明確にしましょう。
3.コメントに情報を詰め込みすぎない
・コメントは、コードの補足説明として、必要最低限の情報に絞って書くようにしましょう。
・あまりに情報量が多いと、コメントを読むこと自体が負担になってしまいます。
簡潔なコメントを書くためのポイント
1.明確な言葉を使う
曖昧な表現や回りくどい表現は避け、簡潔で分かりやすい言葉でコメントを書きましょう。
2.冗長なコメントを避ける
コードを読めばわかることをコメントで説明するのは避けましょう。
コメントは、コードの意図や補足説明など、コードだけでは表現できない情報を記述するために使いましょう。
3.関数や変数名で表現する
コメントで説明する代わりに、関数や変数に分かりやすい名前をつけることで、コード自体を理解しやすくすることができます。
まとめ
今回は、「リーダブルコード」第6章「コメントは正確に、簡潔に」の内容をまとめました。
コメントは、コードの可読性を高めるための重要な要素です。
しかし、書き方によってはその効果を損なってしまう可能性がある、ということもこの章で学ぶことができました。
6章で紹介されているポイントを参考に、「正確で簡潔なコメント」を書けるようにしていきたいですね。
次回は、第7章「制御フローを読みやすくする」についてまとめます。