はじめに

リーダブルコード
読んだので第Ⅰ部までの自分用まとめ

目次

基本原則
名前の付け方
レイアウト
コメント
感想

基本原則

優れたコードとは

「他の人（未来の自分も含む）が最短時間で理解できるコード」のこと

「簡潔さ」と「丁寧さ」のバランスを取る
短い方が読むのに時間がかからない
一方、短すぎて何が書かれているかわからないコードはかえって理解に時間がかかる

名前の付け方

変数や関数、クラス、メソッドなどの名前を定義する時に留意すること

名前に情報を詰め込む

明確な単語を選ぶ

類語辞典などでニュアンスを明確化できる単語を探す

size → height, num nodes, memory bites
stop → kill, pause

汎用的な単語を避ける・使う場面を選ぶ

原則としてtmp, retval, fooのような何の意味も含まない名前をつけることは避ける
ただし、一時的に値を保管するだけの生存期間の短い変数にtmpと名付けるといった場合はかえって変数の役割が明確になるため、使用する場面を選ぶようにする

抽象的な名前→具体的な名前に

「実際のところ何をしている関数なのか」といった視点で命名する
ひとつのメソッドに複数の役割を持たせているケースなど、場合によっては固有の命名を考えるのに伴ってメソッド自体を役割ごとに複数に分割することも考える

接尾辞や接頭辞を使って情報を付加

変数のフォーマット（〇進数など）や値の単位（ミリ秒など）を変数名に加える
セキュリティに関するコードで暗号化されていない（plaintext）パスワードやデータを安全にする処理の前後（untrusted/trusted）の変数を識別できる名前をつける
上記により変数の意味が明確になり、バグに気づきやすくなる

名前の長さを決める

スコープ（その変数が使われるコードの範囲）が小さい変数の名前は短くてよい
一般的でない省略形を使用しない

名前のフォーマットで情報を伝える

プロジェクトやチーム内で規約を決める・または既存の規約を使って効率的で一貫性のある命名を行う

誤解されない名前

曖昧な名前を避ける

filter → select, exclude
clip → remove, truncate
length：バイト数、文字数、単語数
booleanの値にはis, hasなどを頭につける

数の範囲

限界値を含める時はmin/max
範囲を指定する時はfirst/last
包含～排他的な範囲はbegin/end

ユーザの期待に合わせる

単語が持つ一般的な意味（イメージ、ニュアンス）に則って命名する
複数の名前を検討し、一番誤解を生む確率が低いものを選ぶ

レイアウト

一般的で一貫性のあるレイアウト

改行位置を揃えてシルエットを美しくする
重複している部分を簡略化すれば結果的にコードが簡潔になる
変数の定義などが並ぶ時、意味のある順番に並べる（ビューで表示される順、重要度、アルファベット順など）

似ているコードは似ているように見せる

改行やスペースで縦の線を揃える
似ていない部分＝強調したい部分が目立ち、読みやすくなる
記述にルールができた結果、コードの追加が簡単になる

関連するコードはブロック化

ブロックに分け、それぞれ何のブロックかコメントをつける
ブロックはコードの役割や処理の内容で分ける

コメント

コメントすべきこと

コメントの目的：書き手の意図を読み手に知らせること

コメントするべきではないケース

コードからすぐわかることをコメントに書かない
コードだけでは意味が明確でない時、コメントをつける前にコードを改善（自己文書化）する

コードを書いている時の考えの記録

コードや定数がなぜこの書き方・値になったのか、背景を書いておくと、読み手が無用な改善を試みることがなくなる
コードの欠陥についてコメントしておくことで、読み手も改善について考えたり、コードを追加する時に留意することができる
注意点や要改善点をXXX:、TODO:と頭につけてコメントするとわかりやすい

読み手がコードを解釈するのに必要な情報

コードを読んで質問されそうな部分に先回りで回答をコメントする
コードの一般的でない部分や、誤解されそうな書き方の意図をコメントであらかじめ説明しておく
コードのファイルの最初にそのコードの全体像や目的をコメントする
コードのブロックごとにもそのブロックを要約したコメントをつける

簡潔で正確なコメント

簡潔なコメント

１行でまとめられるコメントは１行で書く
長い文章のコメントを、情報密度が高く短い単語で説明できないか検討する

正確なコメント

「それ」「これ」といった読み手が解釈する必要のある代名詞を避ける
実際このコードが動いた時に何が起こるか具体的な状態を記載し、歯切れの悪い文章をブラッシュアップする
コードが行っている動作を正確に記述する

コードの処理の実例をコメントする

コードがアウトプットする結果を実例で示す
この時、実例の内容は、そのコードに何ができて何ができないかわかるものであるのが望ましい

コードの意図をコメントする

コードの動作をそのままコメントする以外に、それが何のための記述であるのか、詳細レベルでなく高レベルの意図を記録する

名前付き引数コメント

数値やboolean値の引数が何の値であるのかわかりづらい時、インラインコメントで示す

感想

本は通読したが後半はまだ理解できない部分が多く、この記事もとりあえず第Ⅰ部までの内容をまとめることにした。
第Ⅱ部以降は例示のコードを見てもまだ自分の経験不足でどこに問題があるのかピンと来ず、例から話の趣旨を腹落ちさせるところまで至っていない。
定期的に読み直してさらに理解を深め、その際にこの記事も更新したい。