この本の目的は、読みやすいコードを書くことです。読みやすいとは、誰かが読んだとき、理解する時間を最短にするということです。
いい名前をつける。適切なコメントを書く。意味のある単位に分解する。きれいに整形する。こうした基本的なことを説明しています。
この本を読んでから、いくつか名前の付け方がかわりました。
ループイテレータ
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) {Code language: JavaScript (javascript)要約
第１部 表面上の改善から、主に名前の付け方を要約して紹介します。
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");Code language: JavaScript (javascript)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')Code language: JavaScript (javascript)コードを空行で「段落」に分割すると、すばやくコードを読める。
5章 コメントすべきことを知る
コードからすぐにわかることは、コメントすべきではない。例えば「//コンストラクタ」など。
ひどいコードは、コメントを書くより、名前を変更したり、コードを修正しよう。
定数は、値の決め方、なぜその値なのか、についてコメントを書く。例えば NUM_THREADS = 8に対して、「値は >= 2 * num_processorsで充分」など。
ファイルやクラスに「全体像」のコメントを書く。新しくチームに参加した人に説明するような、ファイルやクラスの注意点など。
6章 コメントは正確で簡潔に
「それ」や「これ」などあいまいな代名詞を避ける。「データ」や「キャッシュ」など具体的な名詞を使おう。
入出力の実例をコメントに書く。
// 'src'の先頭や末尾にある'chars'を除去する
// 実例：Strip("abba/a/ba", "ab")は"/a/"を返す
String Strip(String src, String chars)Code language: JavaScript (javascript)
