【最初に】
英語版リーダブルコード(The Art of Readable Code)を読んで日本語訳で要点を殴り書きしてみた。
英語からの翻訳なのでやや口語的でない文章になりますが、
我慢して読んで頂けると幸いです。
【1】 理解しやすいコード
コードは理解しやすくなければならない。
コードは他の人が最短期間で理解できるように書かなければならない。
コードは短くしたほうがいい。だけど「理解するまでにかかる時間」を短くするほうが大切
【2】 名前に情報を詰め込む
•Choosing specific words
明確な単語を選ぶこと。
Get → FetchやDownload。
•Avoiding generic names (or knowing when to use them)
「tmp」や「retval」の汎用的な名前を使わない。
tmp - その変数において一時的である事が最も重要な時のみに使用する事。
•Using concrete names instead of abstract names
抽象的な名前ではなく、具体的な名前を使用。
ServerCanStart() → CanListenOnPort()
•Attaching extra information to a name, by using a suffix or prefix
接頭辞や接尾辞を追加の情報を名前に付ける。
•Deciding how long a name should be
名前をどれ位長くするか決める事。
•Using name formatting to pack extra information
大文字の使用、アンダースコアなどを使って意味のある方法で使う。
「_」をクラスのメンバで使用して、ローカル変数と区別する。
短い名前は短い範囲ではOK。
(ex)
document → doc
string → str
【3】 誤解しない名前
「誰かがこの名前で他の意味で誤解しないか？」を自分自身で精査せよ。
max_ or min_ を使う。
Naming Booleans
・is, has, can, or should can がベター。
・変数に否定の条項を入れない事。
【4】 美学
•Use consistent layout, with patterns the reader can get used to.
•Make similar code look similar.
•Group related lines of code into blocks.
【5】 コメントすべき事を知る
■書くべきでないもの
・コード自体から容易に連想出来る事。
・悪いコードを補足するコメント。それなら悪いコードを直そう。
■記録する必要がる考える
■読み手になって考えてみる。
・コードやコメントのどの部分が読む人に疑問になるか予想する。
・平均的な読者が予期しない驚くべき行動を文書化する。
・読み手がコード迷わないように、コードをブロック毎に要約する。
【6】 Making Comments Precise and Compact
■コメントとコンパクトに
■“it” や “this” が複数のものを指す可能性がある代名詞を避ける
■実用的な関数のコードの正確な振る舞いをコメントせよ
■input/outputの例を用いて説明せよ
■自明の詳細よりもコードの高レベルでの意図を記載せよ
■多くの意味の言葉で簡潔にコメントせよ
【7】 Making Control Flow Easy to Read
■ネストは浅くしよう。
【8】 Breaking Down Giant Expressions
【9】 Variables and Readability
・変数が多くなるほど、追跡が困難に
・変数のスコープが大きくなるほど、その追跡が困難に
・変数の値が変わるほど、現在値の追跡が困難に
【10】 Extracting Unrelated Subproblems
【11】 One Task at a Time
「一度にひとつのタスク」を行う
・動いているタスクをリストに上げる。
関数やクラスに分ける事も出来れば、1つの関数内での論理的な段落になる。
【12】 Turning Thoughts into Code
おばあちゃんに説明出来なければ、完全に理解してるとは言えない。
(アルベルト・アインシュタイン)
・plain English(専門用語抜きの英語)で同僚に説明するように、 コードで説明せよ。
・その説明でキーワードやフレーズに注意を払おう。
・その説明に一致するようにコードを書こう。
【13】 Writing Less Code
最も読みやすいコードはコードを全く書かない事である。
コードベースを出来るだけ小さくしておく事がベスト。
・複製コードは除いて、出来るだけ多くの汎用コードを作成する。
・使ってないコード、役立たずの機能を削除。
■ライブラリに慣れ親しもう
15分かけてライブラリの関数名、モジュール名を読んでみよう。
これはライブラリ全体を覚えるのではなくて、「これ見たことあるぞ！」
と次の機会に生かす事が出来るのである。
【14】 Testing and Readability
■テストしにくいコードの特徴と、どういう問題を引き起こすか
| 特性 | テスト容易性の問題 | 設計の問題 |
|---|---|---|
| グローバル変数の使用 | テスト毎にグローバル状態をリセットする必要がある。(そうしないと異なるテストでお互いにインターフェースしてしまう) | どの関数が影響するか理解しずらい。関数単体で考える事が出来ず、他に影響があれば全体を理解しなければならない。 |
| 外部コンポーネント依存するコード | セットアップが難しく、テストが難しい。テストを避けるようになる。 | 依存関係が失敗すると、システムが自体も失敗しやすくなる。変更による影響範囲を理解するのが難しい。クラスのリファクタが難しい。システムが失敗しやすくなり、リカバリの方法も難しい。 |
| 非決定論的な振る舞いをするコード | テストは当てにならず、信頼出来ない。 | プログラムは競合状態、非再現性のバグが発生しやすくなる。プログラムを推理しずらくなり、作成途中のバグは追うのも直すのも難しい。 |
further reading
参考文献
Code Complete