酒と泪とRubyとRailsと

Ruby on Rails と Objective-C は酒の肴です!

読みやすいコーディングの心得 [リーダブルコード]

読みやすいコードは、一緒にコーディングするチームのためだけではなく、自分のためにもとても重要です。 今回は「読みやすいコード」を書くための要素をまとめてみました!


一番大切にすべきことは読みやすさ

プログラミングでは、コードを書く時間よりもコードを読む時間の方が多くなります。 複数人で開発をしていると他人の書いたコードを読むことも増えるでしょう。 だから、コードは理解しやすさはプログラマーが最も大切にすべき指標の一つです。

プログラミングが読みやすければ、こんなメリットがあります。

- 他の人がコード読みやすくなって、開発する時間が増える
- コードの読み間違いが減って、バグを生み出しにくくなる

名前で他の人が最短時間で理解できるようにコードを書く

  • モージュール名・クラス名・変数名を 短いコメントと考えて 情報を埋め込む
  • 相手に意図を伝えるために名前には、 明確な単語 を選ぶ
  • エンティティの 目的や値 が明確になるようにする
  • 変数名に 値の単位や制限、危険・注意を喚起する情報 を載せる
  • 変数の スコープ(影響範囲) を意識する。スコープの大きな変数には長い名前をつける
  • プロジェクトや言語の規約を守る。 フォーマットをうまく活用する

一貫性のあるやり方で「整形」する

一貫性のあるやり方でレイアウトを揃えると、他人がソースコードをずっと理解しやすくなる。 例えば次のようなことである。

* 縦の線を真っ直ぐにする(列を整列させる)
* 適切な位置で改行する
* 並び順に一貫したルールを持つ(アルファベット順、種類別、重要度など)
* 空行を使ってコードを論理的な段落(似ているグループ)に分ける
1
2
3
4
5
6
7
// 例)
TcpConnectionSimulator(
  500,  /* Kbps */
  80,   /* millisecs latency */
  200,  /* jitter */
  1     /* packet loss */
)

コメントは書き手の意図を読み手に知らせるためにある

コメントは書き手の意図を読み手に伝えるための重要な情報の一つです。 プロジェクトの規模や、言語の特性によってコメントの量は変わりますが、 大切なことは、「読み手の立場」に立ってコメントを残すことだと思います。

  • コードからわかることをコメントに書かない
  • コードを書いている時の 自分の考え を記録する
  • コードの欠陥・ハマりそうな罠 を知らせる(TODO/FIXME/HACK/XXXなど)
  • 読む人が 質問 しそうなことを書いておく
  • 全体像を 要約 したコメントを残す
  • コメントの曖昧さを排除する、動作を明確に記述する( 実例 を残す)

制御フローを読みやすくする

  • 条件式は左側に 変化する 値、右側にあまり 変化しない 値を置く
  • 基本は、if/elseを使う。三項演算子は 簡潔 になる時だけ使う
  • 関数からできる限り 早く返す
  • ネストを 浅くする ことで、読み手の負荷を減らす
  • 巨大な式は 分割 して、読み手が1つ1つ飲み込めるようにする

変数と読みやすさとの関係

  • コードの理解を助けない邪魔な変数は作らない
  • 変数の スコープを小さくする (変数が見えるコードの行数をできるだけ短くする)
  • 変数を操作する場所をできるだけ減らす(イミュータブルはトラブルになる傾向が少ない)

読みやすさを意識したリファクタリング

  • ライブラリ (標準ライブラリ、APIやパッケージ)を有効に活用する
  • ロジックを 簡単な言葉 で説明できるようなコードにする
  • 一度に1つのことだけ処理する ように関数(クラス)を分割する
  • できるだけコードを 小さく保つ 、必要になるまで作らない(You Ain’t Gonna Need It./YAGNI)
  • 汎用的なコード を独立したライブラリにすることで、プロジェクトを小さく保つ

テストを読みやすくする

  • テストにやさしいコードを設計 する
  • テストコードもメンテナンスコストがかかる。だから、テストコードは必要なテストだけにする
  • バグの発見・修正 が容易になるように、エラーメッセージを読みやすくする
  • コードを効果的にテストする最も単純な入力をテストに使う
  • テストの関数に名前をつけて、何をテストしているかわかるようにする

コードを読みやすく保ち続ける

本書に書いてあることと少し逆行しますが、プロジェクトが将来どんなふうに進むかを 意識してコードが「読みやすくあり続ける」ために設計・実装を行っていきたいです。 そうすることで開発しやすいコードが保ち続けられると思います!

(補足) 粒度を一定に保つ

脱・読みづらいコード!今日から一段上のプログラマーになる方法 5 選』 がすごく勉強になったのでその抜粋です。

コードの中のメソッドの切り出し等で粒度を一定にすることで理解を助ける。 この練習には『コメントコーディング(日本語で一定の粒度で処理の設計を行う)』が有効。

また文章のように処理を順番に書くのではなく、概念を理解してそれにもとづいて書くことで オブジェクト指向を意識した設計となる。これにより、役割の分担を行うことができる。

おすすめの書籍