【リーダブルコードまとめ】第6章:コメントは簡潔かつ正確に

どうも、今回は「リーダブルコードの第6章:コメントは簡潔かつ正確に」を、ざっくりまとめておきたいと思います。

結論から言うと「コメントは領域に対する情報の比率を高くする!」がポイントです。そのための方法を以下にまとめておきます。

【リーダブルコードまとめ】第6章:コメントは簡潔かつ正確に

「それ」「あれ」などの代名詞を使わない

複数のことを指し示すことがあり得る、代名詞をコメントに使わないようにしましょう。あれ、それ、これ、どれ、などですね。

これらの代名詞を使うことで、コメントが理解しにくいものになってしまう可能性があるからです。

関数の動作をできるだけ正確に説明

難しい部分ですが、関数の動作はできるだけ正確に、かつ簡潔に説明できるように注意しましょう。ダラダラと書いているとものすごいコメントになってしまいます。関数の目的は何かをまとめます。

コードの意図は高いレベルで記述する

コードの意図は詳細レベルではなく、高いレベルで記述します。理由はコメントは簡潔かつ高密度に情報を与えることが目的だからです。

例えばある処理によって昇順に値段を表示するとします。

この時にlistを逆順にイテレートするといったようなコメントではなく、値段を高い順に表示するといったようなコメントがついていた方が、より高いレベルからのコメントになります。

よくわからない引数にはインラインコメントを使う

よくわからない引数や変数には、コメントをつけてあげるとわかりやすくなります。

言葉や表現を厳選してコメントを簡潔に保つ

コメントに使う言葉を厳選することで、高い情報量を含ませて、コメントを簡潔に保つことができます。

例えば、「所在地から余分な空白を除去する。それからAvenueをAve.にするなどの整形を施す。こうすれば表記が僅かに違う所在地でも、同じものと判別できる。」といったコメントは、「所在地を正規化する。」で終了です。

このようにコメントは言葉や表現を厳選してつけるようにしてください。

コメントを残す

メールアドレスが公開されることはありません。

CAPTCHA