【結論】
・名前を見ただけで情報が読み取れるような命名を行う
・一貫性と意味のあるスタイルでコードを整形する
・コードから直ぐ読み取れる事はコメントしない。コードを理解するのに役立つものにコメントする
【目次】
- リーダブルコードとは
- 第1章:理解しやすいコード
- 第2章:名前に情報を詰め込む
- 第3章:誤解されない名前
- 第4章:美しさ
- 第5章:コメントすべき事を知る
- 第6章:コメントは簡潔で正確に
- 参考情報
- 《今日の学習進捗(3年以内に10000時間に向けて)》
【本題】
リーダブルコードとは
副題の通り、より良いコードを書くためのシンプルで実践的なテクニックが詰まった本
第1章:理解しやすいコード
「良いコードとは、他の人が最短時間で理解できるように書かれたものである」
第2章:名前に情報を詰め込む
変数・関数・メソッド・クラスなどに名前をつける際は、それらを表す情報を詰め込む (そのメソッドが何を返すのか?その変数がどういった値を持っているのか?)
その為のノウハウは下記の通り。
・明確な単語を選ぶ
解釈の範囲が広い単語より、限定的な意味合いの単語の方が、メソッドの動きなどが伝わりやすい
例) ・get → download、fetch
・size → height、NumNodes、MemoryBytes
・stop → kill、resume、pause
・find → search、extract、locate、recover
・start → launch、create、begin、open
・make → setup、build、generate、compose、add、new
・汎用的な名前は避ける
なんの意味も含まない名前ではなく、データの値や目的を表した名前を付ける(明確な意図がある場合は別)
例)
・抽象的な名前よりも具体的な名前を使う
変数やメソッドの動作をそのまま表すような名前を付ける。
例)
・ServerCanStart→CanListenOnPort
・DisallowEvilConstructors→DisallowCopyAndAssign
・—run_locally→—extra_logging
・接尾辞や接頭辞を使って情報を追加する
時間やバイト数などの計測できるものは変数名に単位を入れると良い
例)
delay→delay_secs
size→size_mb
limit→max_kbps
angle→degrees_cw
変数の意味を勘違いすると深刻な被害が出る箇所は、危険や注意を喚起する情報も追加した方が良い
例)
password(処理前に暗号化する必要があるプレインテキスト)→plaintext_password
comment(表示前にエスケープする必要があるコメント)→unescaped_comment
html(文字コードをUTF-8に変えている)→html_utf8
data(URLエンコードしているデータである)→data_urlenc
・名前の長さを決める
スコープが小さければ、近くにその変数・メソッドの情報が集約されているので、名前は短くても良い (ブロック引数のiなどが良い例)
頭文字を使った省略は、新規でアサインされた人でも分かるレベルの内容に留める (stringをstrと略すような一般的なレベルに抑える)
単語の不要な部分は切り捨てる
例)
ConvertToString→ToString
DoServeLoop→ServeLoop
・名前のフォーマットで情報を伝える
Rubyなら、クラス・モジュール名はキャメルケース、定数は全て大文字の_区切りなど
第3章:誤解されない名前
・filter(選択するのか?除外するのか?分からない)→select、exclude
・clip(文字を削除するのか?切り詰めるのか?)→remove truncate
・限界値を明確にするには、名前の前にmaxやminを付ける
・範囲を指定する時は、firstとlast、minとmax、beginとendの様に、包括関係が分かる単語を用いる
・ブール値(tureかfalse)の場合、頭にis・has・can・shouldなどを付けるとわかりやすい。
・単語に対する期待にも注意する(get、sizeなどは軽量な処理だと期待される)
第4章:美しさ
一貫性のあるレイアウトを使う(チーム内のコード規約に従う)
似ているコードは似ている様に見せる、関連するコードをまとめてブロックにする
・一貫性のある簡潔な改行を行う(同じルールでコードを折り返す)
・メソッドを使った整列(メソッドにまとめて、コードを折り返さずに済む様にする)
・縦の線は真っ直ぐにする(同じメソッドが並ぶ場合、引数の位置が揃う様に空白を入れる)
・一貫性と意味のある並び順(フロントに表示される並び、重要度、アルファベット順)
・宣言をブロックにまとめる、コードを段落に分割する(グループごとにコメントで区切る
第5章:コメントすべき事を知る
・コードからすぐにわかることはコメントに書かない(ひどい名前はコメントをつけずに名前を変える)
・監督コメンタリーを入れる(他の実装方法との比較や、コードが汚い理由など)
・コードの欠陥にコメントを付ける(TODO:)
・定数にコメントを付ける(定数である理由や背景)
・質問されそうな事をあらかじめ記述する
・ハマりそうな罠を告知する
・全体像のコメント(データの流れ、クラスの連携など)
・細部に捕らわれない様に要約コメント(塊を関数に分割できるのであれば、そちらがベター)
・コードを理解するのに役立つものなら何でもいいから書こう(WHYのみ書くだと、人によって受け取り方が異なる場合がある)
・よく分からない引数には、名前付き引数を使う(非対応の言語ではインラインコメント)
第6章:コメントは簡潔で正確に
・コメントは簡潔に保つ(情報密度の高い言葉を使う)
・あいまいな代名詞は避ける(「それ」「これ」など)
・関数の動作を正確に記述する(例:行数を数える→改行文字'\n'を数える)
・概念的な説明が難しければ、入出力の実例を示す
・コードの意図を書く(listを逆順にイテレートする→値段の高い順に表示する)
参考情報
書籍「リーダブルコード: より良いコードを書くためのシンプルで実践的なテクニック」
《今日の学習進捗(3年以内に10000時間に向けて)》
本日クライアントから、バグの報告があったが、改めてテストケースの設定が十分で無かったと実感した。
バグの内容としては、IEで一般ユーザーのダッシュボード一覧を表示すると、応募フォームへ遷移する為のボタンが消えるという事象だった。
テストケース製作途中で実装された箇所だった為、突貫的にテストケースに取り込んだが、IEのテストには盛り込んでいなかった。
テストケースの作成と開発を同時並行で進める場合は、テストケース作成に着手した時点と作成後の差分を漏れ無くチェックする必要があると実感した。 また、差分機能のテストケースを作成する際に、バグの見逃しを防ぐ為にも、テストの観点(表示をテストするのか?IEでもテストも必要か?権限別にテストすべきか?など)は整理しておく必要があると感じた。
とはいえ、限られた時間の中で、全てのバグを検出するのは困難なので、とにかくクリティカルなバグだけは混入しないことに注力していきたい。
学習開始からの期間 :190日
今日までの合計時間:1846h
一日あたりの平均学習時間:9.8h
今日までに到達すべき目標時間:1735h
目標との解離:111h
「10,000時間」まで、
残り・・・「8154時間!」