Open yuyanegishi opened 5 years ago
変数や関数、クラス定義等、様々な場面で名前を付けるシーンがあり、その名前は短いコメントでより他者に伝わりやすい文言でなければならない。
"get"という単語のように用途や情報が不明確な単語は避ける。具体的には、インターネットから情報を取ってくるのであれば、fetchpage()という関数名にする等、より具体的な情報を端的に伝える名前であることが好ましい。
tmpやretval、fooなどの汎用的な名前を付ける際は何かしらの目的がない場合は避けた方が好ましい。また、ループ構文のイテレーターに関しても、汎用的な名前（i、j、k等）は「イテレーターである」という意味しか持たないので、繰り返しが行われる変数が教師のidであればteacher_idのような名前の方が、コードの目的やバグの対応の際に意味が理解しやすく好ましいとされる。
変数や関数等の構成要素の名前は、抽象的ではなく具体的なものにする方が好ましい。具体的にどういった動作が行われるのかが明確になっている名前である方が、他者が見た際にどういった変数や関数なのかが理解しやすい。
単位や属性を名前に組み込むことで、変数等の形式がわかりやすくなる。具体的には遅延時間を表す変数名をつける際には、delayのみでなくdelay_secsのように単位がわかるように設定した方が好ましい。
原則長すぎる名前は覚えにくい、かつコードの量が増えてしまうため好ましくない。省略しても良い情報と重要な情報を分けたり、単語を省略したりして、より端的にわかりやすい名前を付ける必要がある。ただ単語の省略に関してはstringをstrにするなど、汎用的な単語の省略は周囲に理解されるものの、プロジェクト固有の省略方法については他者から理解されない場合も多いので、避ける方が好ましい。
クラス名は大文字始まる等、大文字小文字での判別やアンダースコアを使った判別も活用することで、表す情報を明確にすることも実践できる。
いくつかの具体例のみ下記に記載。
filter()：「選択する」のか「除外する」のか明確ではないので、「選択する」であればselect()、「除外する」であればexclude()などの名前を使用した方が好ましい。
範囲の指定：minやmax、firstやlastを活用して、以上以下、より上未満などの関係性を端的に明確に示す。
一貫性と意味のある形式でコードの見た目をまとめることで、読みやすいコードにする。
コードが長くなってしまったことのみで改行を行なってしまうことで、一貫性がなくなってしまうことを避ける。
同様な処理を複数回行う際は、ヘルパーメソッドを使用することで、コードを簡略化する。
関数の引数やリスト等、縦の線を統一することでどこに何の要素が入っているかを明確にする。
変数の定義など、複数の要素やコードを羅列する際は、重要度順やアルファベット順など、意味のある順番で並びべ方を統一することで、一貫性を保つ。
コードを意味ある塊として分割することで、それぞれのコードの意味や処理内容を明確にすることで、読みやすいコードにする。
目の前のコードからしか情報を読み取ることができないので、必要な情報があればコメントを残して意図や内容を伝える。
判断理由の記載 コードの記載方法に複数の選択がある場合等は、何故その選択にしたのかをコメントすることで、他者の考える時間を省略することができる。
改善内容、現状の記載 コードに不備や欠陥、未完成なコード等、改善が必要な場合はその旨を記載することで、今後の方向性や現状を明確に伝えることができる。
要約コメント 関数の定義等、詳細を調べなくても概要が把握できるようなコメントを書くことで、行われている処理の目的や内容を知ることができる。
コードからすぐにわかることはコメントしない 「# ○○クラスの定義」などコードを読めばすぐにわかることはコメントしない
関数名や変数名の補足をするようなコメントをしない 抽象的な名前の補足をするためにコメントをするのではなく、名前自体を明確なものにする方が好ましい
曖昧な代名詞を避ける 「データをキャッシュに入れる。ただし、先にそのサイズをチェックする」では、“その”がデータを指しているのかキャッシュを指しているのか不明になっている。代名詞を使用する際は、代名詞が指しているものが明確な場合のみ使用する
歯切れの悪い文章は避ける 「○○によって、優先度を変える」ではなく「△△の優先度を高くする」のように、情報を明確にする。
条件やループなどの制御フローは他の場所に飛んだり、枝分かれすることがあるので、コードを上から下に読むだけでは理解できない部分があるので、よりわかりやすいような記載が必要になる。
調査対象を左にして、比較対象を右にする方が好ましい。
エラー時の処理等については、コードの頭に集約し「ガード節」を使うことで、読み手側の負担が減り、読みやすいコードとなる。
ネストが深くなると条件が複数組み合わさり、コードを読む際は前の条件を覚えていなければならないので、なるべくネストを浅くする。
一つの式に含まれているコードの塊が大きいと、それだけ意味や処理内容を理解するのに時間がかかってしまう。
式の分割させる、または式の重複を減らすためには、式を表す変数を使用することで、式の意味を明確にする、または、無駄なコードを減らすことができる。
上記の説明変数、要約変数による式の分割を用いて、文を丸ごと説明変数の定義とその他の部分に分割することで、一つの大きな文を分割することができ、理解がしやすくなる。
説明変数や要約変数のように式を分割するような目的ではない変数については削除する。
一時的な値の保持、中間結果の保持のための変数の削除 一時的、または中間結果を保持するためだけに変数を用いることは、コードが重複するだけになってしまうので適切ではない。
変数のスコープを縮める グローバル変数のようにスコープが広い変数を使用していると、適用されている範囲が広くなりすぎてしまい、意図せず変数の値を変更してしまったり、また、どの変数ができようされているのか不明確になってしまうことが生じてしまうので、適切に変数のスコープを設定することを徹底する。
複数の処理（オブジェクトを作成したり、データを整えたり）を、一つのコードで行うとコードが理解しにくくなる。
行うことをより細かいタスクにする（「投票結果を受けて、スコアを更新する」を「投票の結果を数値変換」と「スコアに更新する」に分ける等）し、それぞれのタスクを一つのコードで表現することで、一つのコードが行なっている処理が明確になる。
クラス定義によってデータが構造化されているので、オブジェクトから値を抽出することで、一定のルールのもと値を抽出できる。
表示されるエラーメッセージを理解できるものにすることで、どういった不備があるのかを明確にする。
テストの際に設定する入力値を複雑なものにするのではなく、簡潔なものにすることで、どういった目的での入力値なのかを明確にする。
名前の付け方
変数や関数、クラス定義等、様々な場面で名前を付けるシーンがあり、その名前は短いコメントでより他者に伝わりやすい文言でなければならない。
明確な単語を選ぶ
"get"という単語のように用途や情報が不明確な単語は避ける。具体的には、インターネットから情報を取ってくるのであれば、fetchpage()という関数名にする等、より具体的な情報を端的に伝える名前であることが好ましい。
汎用的な名前を避ける
tmpやretval、fooなどの汎用的な名前を付ける際は何かしらの目的がない場合は避けた方が好ましい。また、ループ構文のイテレーターに関しても、汎用的な名前（i、j、k等）は「イテレーターである」という意味しか持たないので、繰り返しが行われる変数が教師のidであればteacher_idのような名前の方が、コードの目的やバグの対応の際に意味が理解しやすく好ましいとされる。
具体的な名前を付ける
変数や関数等の構成要素の名前は、抽象的ではなく具体的なものにする方が好ましい。具体的にどういった動作が行われるのかが明確になっている名前である方が、他者が見た際にどういった変数や関数なのかが理解しやすい。
名前に情報を追加する
単位や属性を名前に組み込むことで、変数等の形式がわかりやすくなる。具体的には遅延時間を表す変数名をつける際には、delayのみでなくdelay_secsのように単位がわかるように設定した方が好ましい。
名前の長さを決める
原則長すぎる名前は覚えにくい、かつコードの量が増えてしまうため好ましくない。省略しても良い情報と重要な情報を分けたり、単語を省略したりして、より端的にわかりやすい名前を付ける必要がある。ただ単語の省略に関してはstringをstrにするなど、汎用的な単語の省略は周囲に理解されるものの、プロジェクト固有の省略方法については他者から理解されない場合も多いので、避ける方が好ましい。
名前のフォーマットで情報を伝える
クラス名は大文字始まる等、大文字小文字での判別やアンダースコアを使った判別も活用することで、表す情報を明確にすることも実践できる。
誤解される名前を避ける
いくつかの具体例のみ下記に記載。
filter()：「選択する」のか「除外する」のか明確ではないので、「選択する」であればselect()、「除外する」であればexclude()などの名前を使用した方が好ましい。
範囲の指定：minやmax、firstやlastを活用して、以上以下、より上未満などの関係性を端的に明確に示す。
見た目の美しさ
一貫性と意味のある形式でコードの見た目をまとめることで、読みやすいコードにする。
改行の位置
コードが長くなってしまったことのみで改行を行なってしまうことで、一貫性がなくなってしまうことを避ける。
重複部分をメソッドを用いてまとめる
同様な処理を複数回行う際は、ヘルパーメソッドを使用することで、コードを簡略化する。
縦の線を合わせる
関数の引数やリスト等、縦の線を統一することでどこに何の要素が入っているかを明確にする。
一貫性を意味のある並び
変数の定義など、複数の要素やコードを羅列する際は、重要度順やアルファベット順など、意味のある順番で並びべ方を統一することで、一貫性を保つ。
コードをブロック毎に分割する
コードを意味ある塊として分割することで、それぞれのコードの意味や処理内容を明確にすることで、読みやすいコードにする。
コメントの活用
目の前のコードからしか情報を読み取ることができないので、必要な情報があればコメントを残して意図や内容を伝える。
自らの考えを記録する
判断理由の記載 コードの記載方法に複数の選択がある場合等は、何故その選択にしたのかをコメントすることで、他者の考える時間を省略することができる。
改善内容、現状の記載 コードに不備や欠陥、未完成なコード等、改善が必要な場合はその旨を記載することで、今後の方向性や現状を明確に伝えることができる。
要約コメント 関数の定義等、詳細を調べなくても概要が把握できるようなコメントを書くことで、行われている処理の目的や内容を知ることができる。
コメントすべきでないこと
コードからすぐにわかることはコメントしない 「# ○○クラスの定義」などコードを読めばすぐにわかることはコメントしない
関数名や変数名の補足をするようなコメントをしない 抽象的な名前の補足をするためにコメントをするのではなく、名前自体を明確なものにする方が好ましい
コメントの正確さ、簡潔さ
曖昧な代名詞を避ける 「データをキャッシュに入れる。ただし、先にそのサイズをチェックする」では、“その”がデータを指しているのかキャッシュを指しているのか不明になっている。代名詞を使用する際は、代名詞が指しているものが明確な場合のみ使用する
歯切れの悪い文章は避ける 「○○によって、優先度を変える」ではなく「△△の優先度を高くする」のように、情報を明確にする。
制御フローの読みやすさ
条件やループなどの制御フローは他の場所に飛んだり、枝分かれすることがあるので、コードを上から下に読むだけでは理解できない部分があるので、よりわかりやすいような記載が必要になる。
条件式の引数の並び順
調査対象を左にして、比較対象を右にする方が好ましい。
if/elseブロックの並び順
関数から早く返す
エラー時の処理等については、コードの頭に集約し「ガード節」を使うことで、読み手側の負担が減り、読みやすいコードとなる。
ネストを浅くする
ネストが深くなると条件が複数組み合わさり、コードを読む際は前の条件を覚えていなければならないので、なるべくネストを浅くする。
大きな式を分割する
一つの式に含まれているコードの塊が大きいと、それだけ意味や処理内容を理解するのに時間がかかってしまう。
説明変数、要約変数
式の分割させる、または式の重複を減らすためには、式を表す変数を使用することで、式の意味を明確にする、または、無駄なコードを減らすことができる。
巨大な文の分割
上記の説明変数、要約変数による式の分割を用いて、文を丸ごと説明変数の定義とその他の部分に分割することで、一つの大きな文を分割することができ、理解がしやすくなる。
変数の扱い方
変数の削除
説明変数や要約変数のように式を分割するような目的ではない変数については削除する。
一時的な値の保持、中間結果の保持のための変数の削除 一時的、または中間結果を保持するためだけに変数を用いることは、コードが重複するだけになってしまうので適切ではない。
変数のスコープを縮める グローバル変数のようにスコープが広い変数を使用していると、適用されている範囲が広くなりすぎてしまい、意図せず変数の値を変更してしまったり、また、どの変数ができようされているのか不明確になってしまうことが生じてしまうので、適切に変数のスコープを設定することを徹底する。
コードで行うことを簡潔にする
複数の処理（オブジェクトを作成したり、データを整えたり）を、一つのコードで行うとコードが理解しにくくなる。
タスクを小さくする
行うことをより細かいタスクにする（「投票結果を受けて、スコアを更新する」を「投票の結果を数値変換」と「スコアに更新する」に分ける等）し、それぞれのタスクを一つのコードで表現することで、一つのコードが行なっている処理が明確になる。
オブジェクトから値を抽出する
クラス定義によってデータが構造化されているので、オブジェクトから値を抽出することで、一定のルールのもと値を抽出できる。
良いテストの設計
エラーメッセージをわかりやすくする
表示されるエラーメッセージを理解できるものにすることで、どういった不備があるのかを明確にする。
入力値を簡潔にする
テストの際に設定する入力値を複雑なものにするのではなく、簡潔なものにすることで、どういった目的での入力値なのかを明確にする。