読みやすいソースコードを書くために
読みやすいソースコードを書くためのポイントをまとめていきます。 こちらは、随時更新していきます。 ※リーダブルコードなどの内容です。学習備忘録として
読みやすいコードとは
- 他人が読んで、理解するまでの速度が最短であるソースコード
命名の際の注意点
変数を命名する際には、なるべく文字列に情報を詰め込みたい。 そのために、下記の点などに注意する。
- なるべく汎用的な表現を避ける。ソースコードの動作を適切に表した命名を考える（意味合いのレンジを狭める）
- なるべく具体的な表現を用いる。単位の概念がある場合は、変数にその情報を含めても良い（ミリ秒など）
- 限界値を表す際は
mim・maxを含める。範囲を指定する際にはfirst・lastを含める。
どこまで詳しく命名するか
意図通り読み取ってもらうために
- 複数の意味にとれる命名は避ける（レンジを狭める、という話と同じ）
- 例えば、
getという表現は暗黙的に単数情報を返すという意味に受け取られる。このように、暗黙的な意味を持つ表現については、期待通り受け取ってもらえるようにする
コメントする際の注意点
コメントすべきこと
- 定数などが決まった背景
- 関数やクラスなどの全体像・どういう役割を持つか
- コード化されていないが、次に書くべきソースコードが決まっている場合（TODO: などの記法を使う）
- 例えば、処理に時間がかかるリスクがあるなど、注意すべき点があるソースコードについては、あらかじめコメントでその旨を伝えるようにする
コメントするべきではない
- コードを見て一目瞭然の事象については、コメントしない
- 例えば、関数名などの説明は、なるべく関数の命名で工夫したい
- プログラムの動作をただ説明しただけのコメントは避ける。動作ではなく「コードの意図」を書くようにする
条件分岐構文の書き方
- 比較を書くときは、変化する値（result）を左に。不変の値（expect）を右側に配置する。
- if else構文において、下記に該当する条件式を先に記述するようにする。 （肯定式・目立つ条件・単純な条件）
- ネストはなるべく浅くする。そのためには、下記のように、単純な条件を先に返してしまえば良い（ガード節）
// 悪い例
if ($result === A) {
if ($result === B) {
return 'B';
}
return 'A';
} else {
return 'C';
}
// 良い例
if ($result !== A) {
return 'C';
}
if ($result === B) {
return 'B';
}
return 'A';
- 条件分岐式は、巨大になることが多い。そんな時は、説明変数を用いる。
// 例
$result = ($input > 1 && $input < 5 && $input !== 3);
if ($result) {
return true;
}
- その他、概念を伝える際なども、変数を積極的に用いる
