リーダブルコード、から名前の付けかたで学んだこと

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

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

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

ループイテレータ

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、と名前をつける方法も使います。

for (int ic = 0; ic < clubs.size(); ic += 1) { for (int im = 0; im < clubs[ic].members.size(); mi += 1) { for (int iu = 0; iu < users.size(); iu += 1) { if (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マニュアルの関数リファレンスが使いやすいのは、「例」があるからです。

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

/* | # | a | action | | - | ----- | --------- | | 4 | <= 10 | my_func_4 | | 3 | <= 20 | my_func_3 | | 2 | <= 30 | my_func_2 | | 1 | > 30 | my_func_1 | */ function my_func(a) {

要約

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

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

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

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

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

for (int ci = 0; ci < clubs.size(); ci += 1) { for (int mi = 0; mi < clubs[ci].members.size(); mi += 1) { for (int ui = 0; ui < users.size(); ui += 1) { if (clubs[ci].members[mi] == users[ui]) {

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

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

3章 誤解されない名前

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

firstとlastも、両端を含む。

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

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

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

4章 美しさ

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

CheckFullName("Doug Adams" , "Mr. Douglas Admas" , ""); CheckFullName(" Jake Brown ", "Mr. Jake Brown III", ""); CheckFullName("No Such Guy" , "" , "no match found"); CheckFullName("John" , "" , "more than one result");
details = request.POST.get('details') location = request.POST.get('location') phone = request.POST.get('phone') email = request.POST.get('email') url = request.POST.get('url')

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

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

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

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

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

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

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

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

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

// 'src'の先頭や末尾にある'chars'を除去する // 実例:Strip("abba/a/ba", "ab")は"/a/"を返す String Strip(String src, String chars)
タイトルとURLをコピーしました