リーダブルコードの要約のメモ（前半）

このメモは「リーダブルコード」を読んだ際のものです。 自分用のメモなので、本の構成の順番を守っておらず、例も本のものではなく自分の理解で置き換えたものになっているので注意してください。

大原則: 優れたコード = 人が最短の時間で理解できるコード

リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック (Theory in practice)

表面上の改善

1. 名前に情報を詰め込む

• 複数の意味を持つ単語や動作の目的がわからない動詞・名詞だけの名前を回避する
• piyo, hogeなどの汎用的な名前を回避して、変数の値を表現する名前を使う
  • ループイテレータを i, j, k ではなく意味を持たせる (i → epoch_i, ei, etc...)
  • 状況に応じて必要な形容詞を考えて加える
    • 大きさをそろえるべき画像データなのにまだ処理前: image → unscaled_imageとしてデータがまだ生のままであることを伝える
    • 本来のデータに処理を加えた: text → text_tfidf(tfidf法を適用したテキストデータ)
  • ミリ秒などの単位を持つ変数に単位を付ける
    • inference_time → inference_time_ms
    • size → memory_size_gb
• 具体的に何をするか明確な名前を付ける
  • 少なくともVOは明確にする
    • --stop → --stop-all-gpu
    • add_noise(X, noise_param1, noise_param2) → add_gaussian_noise(image, mean, var)
• 新しく開発を行う人がそれを理解できるか考える
  • 明らかでない省略形は使わない
  • 不要な単語を除去する
  • エンティティごとに変数名・関数名のフォーマットを区別する
    • DBから取得したデータを持つ変数にDBの頭文字を付けるフォーマットがあれば、すぐにDBの値と分かる
    • jqueryでライブラリ関数($)から呼び出した値を持つ変数は $を接頭辞とする

2. 誤解されない名前

• 関数の取る値と比較して何をするか曖昧な名前を避ける
  • filter(data, classname) → select_class(data, classname)
  • 範囲指定の名前を明確にする
    • first~last, min~max, begin~end
    • 単位を持つ値なら min_ms~max_msなどとしたい
• 開発者が気にしていることを理解してそれを伝えるように記述する
  • get_inference_time(model)では予測モデルのインファレンス時間を実際にモデルを100回して計算しているとは伝わらないので evaluate_inference_time_ms(model, simulate_num=100)などとする
• 複数の名前候補を挙げて誤解の無い名前を絞り込む

3. 美しさ

• 読み手が慣れているパターンと一貫性があるコードに
• 関連するコードブロックをひとまとめに
  • 改行の位置、インデント、コメントの位置を規則正しく
• 規則正しく並べる
  • 似ているコードは似ている組み立て
  • 変数をどの様な順番に並べるか
    • どんな規則を使ってもいい、しかし同じコード内では同じルールを一貫して使うこと
      • アルファベット順
      • 変数の重要度順
      • 使用位置順、変数の持つ値の型順...

4. コメントすべきこと

• コードを見て理解できることはコメントしない
• コードを見てもわからない変数名・関数名はまずその名前を変えられないかを検討する
• なぜこのような構成・選択にしたのかを記録する
• コードの欠陥や例外の恐れがある箇所を指摘する
  • TODO, FIXME, HACK, XXX, ...
  • todo, mabe-latter, ...
• 新しく見た人が知らない可能性が高い・ミスをする可能性が高い箇所にコメントする
  • # adaptive thresholding のカーネルサイズは～だからXXにする
  • # keras のバックエンドが tensorflow の場合XXXのため以下でエラーになる etc..
• 比較的大きなコードブロックの要約を記述する

5. 正確かつ簡潔にコメントする

• 代名詞は使わない
• 関数の入出力を具体例で示す
• 名前付き引数で引数の内容を説明する

ロジックの構造化

6. 制御フローを見やすく

• コードの並び順と書き方を明確に
  • 比較：左辺を調査対象、右辺を比較対象
  • if/else: 否定の比較を使わない、重要な条件を先に
  • 三項演算子: 単純な二変数の比較・代入以外で無理に使わない、理解のしやすさが最優先
• do-while文を避ける
  • continueのわかりにくさ
  • 条件（重要な箇所）を先に記述する
• return
  • 理解しやすさが優先
  • returnを関数末端に持ってくるためだけにコードを複雑にしてはいけない
• go-to文を避ける
• ネストをむやみに深くしない このメモは「リーダブルコード」を読んだ際のものです。 自分用のメモなので、本の構成の順番を守っておらず、例も本のものではなく自分の理解で置き換えたものになっているので注意してください。

大原則: 優れたコード = 人が最短の時間で理解できるコード

表面上の改善

1. 名前に情報を詰め込む

• 複数の意味を持つ単語や動作の目的がわからない動詞・名詞だけの名前を回避する
• piyo, hogeなどの汎用的な名前を回避して、変数の値を表現する名前を使う
  • ループイテレータを i, j, k ではなく意味を持たせる (i → epoch_i, ei, etc...)
  • 状況に応じて必要な形容詞を考えて加える
    • 大きさをそろえるべき画像データなのにまだ処理前: image → unscaled_imageとしてデータがまだ生のままであることを伝える
    • 本来のデータに処理を加えた: text → text_tfidf(tfidf法を適用したテキストデータ)
  • ミリ秒などの単位を持つ変数に単位を付ける
    • inference_time → inference_time_ms
    • size → memory_size_gb
• 具体的に何をするか明確な名前を付ける
  • 少なくともVOは明確にする
    • --stop → --stop-all-gpu
    • add_noise(X, noise_param1, noise_param2) → add_gaussian_noise(image, mean, var)
• 新しく開発を行う人がそれを理解できるか考える
  • 明らかでない省略形は使わない
  • 不要な単語を除去する
  • エンティティごとに変数名・関数名のフォーマットを区別する
    • DBから取得したデータを持つ変数にDBの頭文字を付けるフォーマットがあれば、すぐにDBの値と分かる
    • jqueryでライブラリ関数($)から呼び出した値を持つ変数は $を接頭辞とする

2. 誤解されない名前

• 関数の取る値と比較して何をするか曖昧な名前を避ける
  • filter(data, classname) → select_class(data, classname)
  • 範囲指定の名前を明確にする
    • first~last, min~max, begin~end
    • 単位を持つ値なら min_ms~max_msなどとしたい
• 開発者が気にしていることを理解してそれを伝えるように記述する
  • get_inference_time(model)では予測モデルのインファレンス時間を実際にモデルを100回して計算しているとは伝わらないので evaluate_inference_time_ms(model, simulate_num=100)などとする
• 複数の名前候補を挙げて誤解の無い名前を絞り込む

3. 美しさ

• 読み手が慣れているパターンと一貫性があるコードに
• 関連するコードブロックをひとまとめに
  • 改行の位置、インデント、コメントの位置を規則正しく
• 規則正しく並べる
  • 似ているコードは似ている組み立て
  • 変数をどの様な順番に並べるか
    • どんな規則を使ってもいい、しかし同じコード内では同じルールを一貫して使うこと
      • アルファベット順
      • 変数の重要度順
      • 使用位置順、変数の持つ値の型順...

4. コメントすべきこと

• コードを見て理解できることはコメントしない
• コードを見てもわからない変数名・関数名はまずその名前を変えられないかを検討する
• なぜこのような構成・選択にしたのかを記録する
• コードの欠陥や例外の恐れがある箇所を指摘する
  • TODO, FIXME, HACK, XXX, ...
  • todo, mabe-latter, ...
• 新しく見た人が知らない可能性が高い・ミスをする可能性が高い箇所にコメントする
  • # adaptive thresholding のカーネルサイズは～だからXXにする
  • # keras のバックエンドが tensorflow の場合XXXのため以下でエラーになる etc..
• 比較的大きなコードブロックの要約を記述する

5. 正確かつ簡潔にコメントする

• 代名詞は使わない
• 関数の入出力を具体例で示す
• 名前付き引数で引数の内容を説明する

ロジックの構造化

6. 制御フローを見やすく

• コードの並び順と書き方を明確に
  • 比較：左辺を調査対象、右辺を比較対象
  • if/else: 否定の比較を使わない、重要な条件を先に
  • 三項演算子: 単純な二変数の比較・代入以外で無理に使わない、理解のしやすさが最優先
• do-while文を避ける
  • continueのわかりにくさ
  • 条件（重要な箇所）を先に記述する
• return
  • 理解しやすさが優先
  • returnを関数末端に持ってくるためだけにコードを複雑にしてはいけない
• go-to文を避ける
• ネストをむやみに深くしない