• KM KM
  • — 5 months ago
test

リーダブルコードを読んで

以前に読んだことがあるが戒めも兼ねて読み直し、記事にするためまとめてみました。

まず読みやすさとは?

  • コードは理解しやすく書く
  • "コードは他の人が最短時間で理解できるように書かなければいけない" この"理解する"とは他の人が変更を加えたりバグを見つけることができるという意味である
  • 短い = 理解しやすいではない(後で触れる三項演算子など)

大事だなと思った部分を取り上げ自分なりに簡単にまとめている

名前に情報を詰め込む

明確な単語を選ぶ

getはどこから取得するかわかりにくい。fetchやdownloadなど明確な単語を使う

汎用的な名前の仕様を避ける

temp・fooなどは極力使わない(変数の入れ替えなどでtempを用いるのはOK)

具体的な名前を使う

TCP/IPポートをサーバがリッスンできるかを確認するメソッドでServerCanStart()では抽象的。CanListeOnPort()のように具体的にする

名前に情報を追加する

idではなんのidかぱっと見でわからない。 enemy_idなど情報を追加する

名前の長さを決める

スコープが小さければ短い名前で良い。 略語は一般的ではないものは避ける。 documentの代わりにdocはわかる。しかしプロジェクト独自の省略形は新規参加者が困る

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

PHPならPSR-*に書いてあるものであればそれに準拠すべき(クラス定数なら全て大文字で、区切り文字はアンダースコアで記述する) 変数名はプロジェクトなどに定められたルールに従う

誤解されない名前を用いる

 ブール値の変数名は、頭にis・has・can・shouldなどをつけてわかりやすくする ことが多いが名前を否定形にするのは避けるべき

美しいコード

  • 一貫性のある簡潔な改行位置
  • メソッドを使った整列
  • 縦の線をまっすぐにする
  • 一貫性と意味のある並びにする
  • 宣言をブロックにまとめる
  • コードを段落に分割する
  • 個人的な好みと一貫性

コメント

"コメントの目的は、書き手の意図を読み手に知らせることである"

コメントするべきでは「ない」こと

パット見でわかるコードに対してコメントを書かない

コメントのためのコメントをしない

コメントを書かなければいけないからと言われてとりあえず書いているだけのコメント。所謂"価値のないコメント"は意味がない

ひどい名前やコードはコメントを付けず名前やコードを変える

自分の考えを記録する

なぜコードが他のやり方でなくこのやり方になっているのかなど

コードの欠陥にコメントをつける

「TODO:」,「FIXME:」,「HACK:」などを用いる

定数にコメントを付ける

名前が明確で必要もないものがあるが、その定数の値を決めた時の考えを記述しておくべき。 あと定数の話ではないし、当たり前の話だがマジックナンバーは避けるべき(意外と使っている人が多くて驚く)

読み手の立場になって考える

一般的ではない方法で記述せざるを得ないときはなぜそうしたか記述しておくべき

ライターズブロック(行き詰まってしまって、文章が書けないこと)を乗り越える

とりあえず自分の考えることを書き出しておく。多少変であっても構わない

あいまいな代名詞を避ける

「それ」や「これ」を避けきちんと主語を使う

関数の動作を正確に記述する

"行数を数えて返す"では行数の定義がわからない。"改行文字('\n')を数える"など正確に記述する

入出力に実例を使う

コードの意図を書く

情報密度の高い言葉をつかう

多くの意味が詰め込まれた言葉や表現を使って、コメントを簡潔にかく

制御フロー

条件式の引数の並び順

左側:「調査対象」の式。変化する。 右側: 比較対象」の式。あまり変化しない。

関数から早く返す

関数で途中で処理が必要なくなるケースなどがある。であれば下記のように早めに返すべきである

if/elseブロックの並び順

  • 条件は否定形よりも肯定形を使う。 if (!is_debug)ではなく if (is_debug)にする
  • 単純な条件を先に書く
  • 関心を引く条件や目立つ条件を先に書く

    三項演算子

    return hour >= 12 ? 'pm' : 'am';

    上記のようなシンプルな代入の場合、三項演算子は短く一行でまとめられるが下記みたいに計算するなどして行うと読みにくいだろう

    return exponent >= 0 ? mantissa * (1 << exponent) : mantissa / (1 << -exponent);

    無理をして一行に収める必要はないし、先程触れたが短くする=理解しやすいではない

    do/whileループを避ける

    関数から早く返す

    処理が不要になるケースなど早めに返す

    ネストを浅くする

    ネストが深いと読みにくい

    早めに返してネストを削除する

    ループ内部のネストを削除する

    continueを使ってネストを消せるケースも有る

変数と読みやすさ

変数を削除する

一度しか使っていないので、重複コードの削除になっていないし、$user->idでも十分にわかる

// $userはDBから取得したオブジェクト
$user_id = $user->id
return $user_id;

グローバル変数は避ける

変数のスコープを縮める

一度に考えなけれ ばいけない変数を減らせるから

一度に1つのことを

 一度に複数のことをするコードは理解しにくいため一度に1つのことを行う よみにくいコードがあるなら行われているタスクを列挙し別の関数orクラスに分割できないか検討

KM

Programmer

test

お気軽に
お問い合わせください。

お問い合わせ