『リーダブルコード』第6章 コメントは正確で簡潔に

リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック (Theory in practice)

鍵となる考え方:コメントは領域に対する情報の比率が高くなければいけない

コメントを簡潔にしておく

シンプルに説明できることをダラダラ書かない。

あいまいな代名詞を避ける

// データをキャッシュに入れる。ただし、先にそのサイズをチェックする。

// データをキャッシュに入れる。ただし、先にデータのサイズをチェックする。

歯切れの悪い文章を磨く

コメントを正確にする。

// これまでにクロールした URL かどうかによって優先度を変える。

// これまでにクロールしていない URL の優先度を高くする。

関数の動作を正確に記述する

// このファイルに含まれる行数を返す。

// このファイルに含まれる改行文字(‘n’)を数える。

入出力のコーナーケースに実例を使う

関数・メソッドの機能を全て見せることのできる実例をコメントで示す。

コードの意図を書く

「名前付き引数」コメント

Pythonなど、名前付き引数をサポートしている言語の場合、以下のように書くことができる。

名前付き引数をサポートしていない言語では以下のように書くことで、引数の名前を示すことができる。

全ての関数に名前付き引数コメントを使用する必要は無いが、よくわからない引数には使ったほうがよい。

情報密度の高い言葉を使う

// このクラスには大量のメンバがある。同じ情報はデータベースにも保管されている。ただし、
// 速度の面からここにも保管しておく。このクラスを読み込むときには、メンバが存在してい
// るかどうかを先に確認する。もし存在していれば、そのまま返す。存在しなければ、データベー
// スから読み込んで、次回のためにデータをフィールドに保管する。

// このクラスの役割は、データベースのキャッシュ層である。

コメントを残す