にふうち回避

日々のプログラミング勉強の記録

＊自分自身の勉強の備忘録としての記事がほとんどです．内容の正確性などは担保されません．

リーダブルコード【1-3章】

文献紹介

今回はこちらの1-3章を読んだので，途中ですが内容を紹介します

コードは理解しやすくなければいけない

  • コードは「読む」時間の方が長い

じゃあ，良いコードとは？

  • 読みやすい，即ち 「他人が最短時間で理解できる」 コード
  • 読みやすい ＝ 短い ではない．
  • 様々な状況に於いて「読みやすさ」を当てはめる方法を紹介するのが本書．

名前に情報を詰め込む[1部２章]

名前に情報を詰め込む方法

  1. 明確な単語を選ぶ
  2. 汎用的な名前を避ける
  3. 抽象的な名前よりも具体てな名前をつける
  4. 接尾辞や接頭辞をつかって情報を追加する
  5. 名前の長さを決める
  6. 名前のフォーマットで情報を伝える

1. 明確な単語を選ぶ

GetPage　何をゲットするの？？？

  • 明確な単語をつけるべき.
  • get→どこからとってくるの？何をとってくるの？不明瞭

余談：getなのかsetなのかは丁寧に使い分けよう

var size() なんのサイズなの？

  • オブジェクトの項目数？メモリ数？？

stop どう止めるの？

  • 完全停止っ→kill, 一時停止→pause（対義語：resume）などどのような状態になるか明確なものを選ぶべき

2. 汎用的な名前を避ける

tmpは数行の生存期間のものを選ぶべき

すぐに消えるとしても，数値の書き換えなどに使われるものは別の名前に こういうのはダメ．初めから”user_info”などにするべき

let tmp = user.name();
tmp += "" + user.phone_number();
tmp += "" + user.email();

template.set("user_info", tmp)

ループイテレータが複数ある場合はこれも明確な名前を

i, j, k などを使うとfor文バグが発見しづらくなる． 例えばそれぞれを，names[i] favorites[j] coutories[k] のように使うなら name_i favorite_i countory_i といった名前に変えるとより分かりやすい． ni fi ci と簡潔にしても良い． このイテレータは何に使われてるんか？ が，コードを辿らずともわかるようにしよう

3. 抽象的な名前よりも具体的な名前を使う

  • Webページをクローリングしてデータを収集する関数，どれがいいかな？ A. WebCrawler B. CollectDataFromWeb C. WebWaler
  • 解 A. WebCrawler　　　　　　　→クローリングして何をするのかが不明瞭 不適 B. CollectDataFromWeb 　　 →最終的に何をするのかが明確．適 C. WebWaler　　　　→カッコよく最高にイケているが，抽象的で凡人には理解できない

「宇宙船の名前」とか「コードネーム」なら抽象的でも構わないが…

SpaceX　ロケット着陸用ドローン船 　「Of Course I Still Love You（OCISLY）」

SF小説から取られている．関数名などには使わないようにしよう

万能ゆえに名前と実態がはっきりしないものを作るなら…

色々な機能を持つ複合的な関数を作ったはいいが，いまいち名は体を表せていない．それなら関数を分けるべき．

4. 名前に情報を追加する

値の単位をつけよう

  • size → size_mb
  • delay → delay_hours

    重要な属性情報をつけよう

  • 平文パスワード　→ plaintxt_password
  • UTF-8に変換されたhtml → html_utf8

    5. 名前の長さを決める

  • スコープが小さければ短い名前でもいい． 行き先がすぐにわかるなら短くても良い．
  • 長い名前だってエディタ補完があるので気にしなくて良い 例：anonymous は長い単語だが，略すと分かりづらい． isPostAno →　isPostAnonymous

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

  • クラスのメンバー変数などは接頭に Classname_varA などと付けて区別

    誤解されない名前にする．[1部３章]

    例：filter(‘year <= 2011’)

    これは

  • ‘year <= 2011’　のオブジェクトだけを残すのか
  • ‘year <= 2011’ でないオブジェクトを残すのかがわからない

    範囲指定

  • data_count_limit = 10 → 　最大値なの？最小値なの？
  • 限界値は: min/max で定義しよう

そのほか

  • 範囲指定: first/last　(n番目から→m番目まで )
  • 包含/排他: begin/end　(n年からm年までの間のデータ)

    bool値の名前

    例:　read_password = true;

  • 「もうすでに」よみっとたのか「これから」よむのかが分かりずらい
  • パスワードが必要なら「need_password」，すでにパスワードを読み取って認証済みなら「HasAuth」などにしよう

    ユーザーの期待に合わせる

  • get**() これはオブジェクトに含まれるメンバーの値を返すだけにするべき．整形などはしない方が良い． 例えば平均を求める関数に getMean()などと付けるべきではない． computeMean()などとするべき 実行コストの見積もりを誤り想定より挙動が遅くなる，などの問題につながりかねない．

    複数の名前を検討するのも良い．

    他人が見てどれが実態にあった名前かを議論し，良い名前にしていこう

引き続き読み進め，読みやすく分かりやすいコード実装にしてゆきます🙋‍♂️