Pocket

この本の目的は、読みやすいコードを書くことです。読みやすいとは、誰かが読んだとき、理解する時間を最短にするということです。

いい名前をつける。適切なコメントを書く。意味のある単位に分解する。きれいに整形する。こうした基本的なことを説明しています。

この本を読んでから、いくつか名前の付け方がかわりました。

ループイテレータ

i・j・kは配列インデックスやループイテレータによく使われる。もっといい方法は、変数clubsのイテレータならclubs_iかci、変数membersのイテレータならmembers_iかmi。

2.2 ループイテレータ p14

今でも、i・j・kはよく使います。本の方法 ciやmiも使います。変形バージョンの、iを先頭にして、clubsならic、membersならim、usersならiu、と名前をつける方法も使います。

範囲

firstとlastは両端を含むときに使う。beginとendは始点を含み、終端を含みないときに使う。

3.4 範囲を指定するときはfirstとlastを使う p32

lastとendの違いはピンときませんでしたが、終端を含む含まないを区別したいと思い、次のように、変数名の最後に _ge や _lt をつけた名前を使うようにしました。

from_gtより大きい始点を含まない
greater than
from_ge以上
始点を含む
greater than or equal
to_lt未満
終点を含まないless than
to_le以下
終点を含む
less than or equal

カンマや代入イコールの位置を揃える

列を「整列」させると、コードが読みやすくなる。連続した行のカンマやイコールの位置を揃える。

4.4 縦の線をまっすぐにする p47

ぼくは列の位置が揃っていないと読む気がしないので、読むだけのために列の位置を揃えることがあります。他の修正はせず、整列だけして「コード整形」でコミットすることがあります。

コードを段落に分ける

(空行のない)ひと塊りのコードは誰も読む気がしない。

4.7 コードを「段落」に分割する p50

要約コメントは、関数の内部にある大きな「塊」につけてもいい。塊を関数に分割できるならそうしよう。

要約コメント p67

関数内部の連続したコードを空行で段落に分けます。段落に要約コメントが必要そうなら、その段落を関数に分割します。

入出力の実例

入出力の実例をコメントに書いておく。

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

ぼくは、引数や戻り値のdocコメントよりも、メソッドの使い方の例のほうが役に立ちます。phpマニュアルの関数リファレンスが使いやすいのは、「例」があるからです。

実例だけでなく、決定表をコメントに書くことも多いです。決定表をメソッドのコメントに書くのか、テストケースのコメントに書くのか悩んで、どちらにも同じ決定表を書くことが多いです。

要約

第1部 表面上の改善から、主に名前の付け方を要約して紹介します。

2章 名前に情報を詰め込む

インターネットからページを取ってくるメソッドなら、GetPage()よりも、FetchPage()やDownloadPage()のほうがいい名前だ。

i・j・kなどの名前は、インデックスやループイテレータでよく使われる。

次の例では、clubsのイテレータに ci、membersのイテレータにmi、usersのイテレータにuiと名前をつけている。

変数名に時間やバイト数などの単位をいれる。例えば、秒なら、_sec。

スコープの大きい変数には、長い名前をつける。スコープが小さい変数には、短い名前をつける。

3章 誤解されない名前

名前の前の min_ と max_ は、両端を含む。

firstとlastも、両端を含む。

beginとendは、始点を含み、終端を含みない。

ブール値は、頭に is・has・can・shouldなどをつける。

ブール値の名前には、なるべく否定形を使わない。否定形のfalseは理解に時間がかかるため。

4章 美しさ

カンマや代入のイコールの位置を次のように整列すると、流し読みが楽にできる。

コードを空行で「段落」に分割すると、すばやくコードを読める。

5章 コメントすべきことを知る

コードからすぐにわかることは、コメントすべきではない。例えば「//コンストラクタ」など。

ひどいコードは、コメントを書くより、名前を変更したり、コードを修正しよう。

定数は、値の決め方、なぜその値なのか、についてコメントを書く。例えば NUM_THREADS = 8に対して、「値は >= 2 * num_processorsで充分」など。

ファイルやクラスに「全体像」のコメントを書く。新しくチームに参加した人に説明するような、ファイルやクラスの注意点など。

6章 コメントは正確で簡潔に

「それ」や「これ」などあいまいな代名詞を避ける。「データ」や「キャッシュ」など具体的な名詞を使おう。

入出力の実例をコメントに書く。

Dustin Boswell, Trevor Foucher,角征則 オライリー・ジャパン 2012-06