こんにちは！ギークフィードシステム開発事業部所属、エンジニアの岩間です。
今回は、新人エンジニアの私が開発を通して学んだ、私なりのコーディング・プログラミングルールを紹介します。
PHPを使った具体例も合わせて紹介します。
目次
コーディング時の基本のマインドセット
はじめに、コードを書くときに気を付けている基本軸・私なりのマインドセットを紹介します。
シンプル、簡潔、必要最低限のコードで！
前提として、プログラミングする上で重要になってくるのが、「単純性」「簡潔性」です。
自分が書いたコードをほかの開発メンバーが読むとき、開発チームに新メンバーが加わったとき、バグを修正するときなど自分以外の人がコードを読んで、何をしているのかぱっとみてわかるように書くようにしましょう。
（※読む気を削ぐようなコードは書かないようにしましょう。。）
そのためにやること
最もシンプルにコードを書ける方法を考える
- 複雑な処理をシンプルに書く。
- 長すぎる処理は関数化する。
不必要なコードを削除する
- 使っていないコード、意味のない処理など不必要なコードは削除する。
同じことをリピートして書かない
- 同じことをリピートして書いている箇所は、まとめて書く方法がないか考える。
- 共通関数化・共通ファイル化する。
- 定数化する、もしくは環境設定ファイルで管理する。
私なりのコーディングルール5つ
①一貫性のある見た目に整える
同一プロジェクト内でインデント、スぺース、改行、並び順は統一するようにします。
NG例とOK例を紹介します。
【NG例】インデント、スぺース、改行、並び順が統一されていない場合
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
public function Hoge($hoge) { if ($hoge === 1) { echo '1です'; } else{ echo '1以外です'; } } public function Piyo($piyo) { if($piyo === 1) { echo '1です'; }else{ echo '1以外です'; } } |
【OK例】インデント、スぺース、改行、並び順が統一されている場合
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
public function Hoge($hoge) { if ($hoge === 1) { echo '1です'; } else { echo '1以外です'; } } public function Piyo($piyo) { if ($piyo === 1) { echo '1です'; } else { echo '1以外です'; } } |
見た目を整えるだけでも読みやすさがだいぶ変わってきます。
インデント、スぺース、改行、並び順を統一することで、コードのシルエットが美しくなり可読性向上につながります。
②名前の付け方のルール
関数名・変数名・ファイル名に情報を詰め込む
- 名前に情報を詰め込む。
- 名前をぱっと見て、何の処理をするのか、何のためのものなのかわかるようにする。
- 一語一句に意味を込める。明確な単語選びをする。
例えば、何かを「つくる」という意味の名前を付けたいとします。
「つくる」と意味の英単語を挙げてみると、make、create、set up、build、generate、compose、add、newなどたくさんあります。
「何を」「つくる」のかにもよりますが、makeなのか、createなのか、それともaddなのか？
ここでどの英単語を選択するかで、名前の意味、ニュアンスが変わってきます。
また、ついつい使ってしまう「get」という英単語ですが、getは指す意味が広いため、
getPage()という名前よりも、fetchPage()、downloadPage()のほうが意味が明確になり、読み手に伝わりやすくなります。
名前から具体的な動作を想像できる、適切な単語選びが鍵となります。
NG例とOK例を紹介します。
【NG例】limitを使用した変数名
|
1 |
$search_count_limit_per_day = 30; |
【OK例】maxを使用した変数名
|
1 |
$max_search_count_per_day = 30; |
NG例の$search_count_limit_per_dayという変数名では、一日の最大検索回数が29回（30を含まない）なのか、それとも30回（30を含む）なのか曖昧になってしまいます。
“limit”という単語は便利ですが限界値を明確にするには”max”という単語に置き換えたほうが誤解が少なくなります。
汎用的な名前を避ける
tmp、retval、itなどぱっと見て何を指しているのかわかない単語は避ける。
名前のフォーマット（命名規則）に気を付ける
命名規則には主に３つ種類があります。
| キャメルケース（camelCase） | 先頭の単語は小文字、先頭以降の単語の先頭を大文字にする命名規則です。ローワーキャメルケースともいい、PHPやjsなどの関数で使われることが多いです。 |
| スネークケース（snake_case） | 単語の間をアンダーバーでつなぐ命名規則です。DBなどで扱われる値に使用されることが多いようです。 |
| ケバブケース（kebab-case） | 単語の間をハイフンでつなぐ命名規則です。HTMLではclass名であったり、ファイル名に使用されることが多いようです。 |
例えば、あるプロジェクトで「クラス名はキャメルケース（camelCase）、変数名はスネークケース（snake_case）を使う」ことが規則なら、そのプロジェクト内でそれらを混合して使わないようにします。
規則を守って書かれた名前は、「これはキャメルケースだからクラス名だな」「こっちはスネークケースだから変数名だな」といったように名前をみただけで区別がつくようになります。
NG例とOK例を紹介します。
【NG例】命名規則が統一されていない場合
|
1 2 3 4 5 6 7 8 9 10 11 |
public function IsPayment-required(Request $request) { $Customer-Rank = $request['customer_rank']; $customerStatus = $request['customer_status']; if ($Customer-Rank === 'A' && $customerStatus === 'active') { return true; } else { return false; } } |
【OK例】命名規則が統一されている場合
|
1 2 3 4 5 6 7 8 9 10 |
public function IsPaymentRequired(Request $request) { $customer_rank = $request['customer_rank']; $customer_status = $request['customer_status']; if ($customer_rank === 'A' && $customer_status === 'active') { return true; } else { return false; } } |
NG例では一つの名前に大文字・小文字・ハイフン（-）・アンダーバー（_）が混在しており、まとまりのない見た目になっています。
OK例では関数名はキャメルケース、変数名はスネークケースで統一して書かれており、全体的にまとまりがでて読みやすくなりました。
③コメントの付け方のルール
意味のないコメントは書かない
- コードをみればすぐわかることなどは書かないようにする。
- 読み手が詰まってしまうような箇所を予想してコメントを書く。
- コメントがないと解読が難しい、コメントが無駄に長くなるのであれば、コメントではなくコードそのものを修正する。
NG例とOK例を紹介します。
【NG例】意味のないコメントを追加した場合
|
1 2 3 4 |
// 検索回数が30回をこえた場合 if($search_count_per_day > 30 ) { // 処理 } |
【OK例】コードそのものを修正した場合
|
1 2 3 4 5 |
$max_search_count_per_day = 30; if($search_count_per_day > $max_search_count_per_day ) { // 処理 } |
NG例のコードとコメントからは、”30”という数字が何を示す数字なのかが伝わってきません。
「// 検索回数が30回をこえた場合」というコメントは、コードを見ただけでも伝わってくるため、あまり意味のないコメントになってしまっています。
NG例のコードを変えずにコメントだけを変えるなら、「// 検索回数が30回（一日あたりの最大検索回数）をこえた場合」などと修正するのが良いと思います。
OK例は、コメントを追加/修正するのではなく、”30”という数字を$max_search_count_per_dayという変数に格納するようにコード自体を修正したものです。
$max_search_count_per_dayという変数名をみるだけで、30が「一日あたりの最大検索回数」であることがコメントがなくてもわかるようになります。
歯切れのよい簡潔なコメントを書く
- 伝えたいことがぎゅっと詰め込まれた単語/表現を使う。
- 「この」「その」など曖昧な代名詞を避ける。
NG例とOK例を紹介します。
【NG例】
|
1 2 |
// ユーザーが〇〇にチェックしたかどうかによって優先度を変える。 // ユーザーがアップロードしたファイルを読み取り、DBに保存する。ただし、先にそのサイズをチェックする。 |
【OK例】
|
1 2 |
// ユーザーが〇〇にチェックを入れた場合、優先度を高くする。 // ユーザーがアップロードしたファイルを読み取り、△△テーブルに保存する。ただし、先にファイルのデータサイズをチェックする。 |
④関数やクラスの使い方のルール
一つの関数につき一つの処理
- 読みにくいコードがあれば、そこで何が行われているか列挙する。
- 分割できそうであれば分割する。
PHPの場合、PHPDocを使用する
PHPでは、ファイルの先頭や関数・クラス・メソッドの直前に、/** ... */のDocコメントという形式のコメントを記載します。
Docコメント内には、ファイルや処理内容の要約、説明、タグ（名前・参考資料、引数・返り値）などを記載します。
PHPDocについての詳しい説明はこちら↓
https://zonuexe.github.io/phpDocumentor2-ja/references/phpdoc/basic-syntax.html#doc
【PHPDocの使用例（ファイル先頭）】
|
1 2 3 4 5 6 7 8 9 10 11 |
/** * 商品検索トップページのコントローラー ←一行で処理の内容を記述 * * このファイルでは商品検索トップページで行う処理 ←詳しい説明（省略可） * に関するコントローラーを書いています。 * * @version 1.0 ←ファイルのバージョン（省略可） * @author Iwama ←書いた人（省略可） * @link <https://laraweb.net> ←関連リンクなど（省略可） * */ |
関数、クラス、メソッドの場合以下の記述が必須となります。
- @var [型] 説明
- @param [型] 変数名 説明
- @return [型] 説明
【PHPDocの使用例（関数）】
|
1 2 3 4 5 6 7 8 9 10 11 12 |
/** 合計支払料金を計算します ←一行で処理の内容を記述 * @param int $tanka 単価 ←引数の説明（必須） * @param int $quantity 個数 ←引数の説明（必須） * @return int 計算した料金 ←返り値（必須） */ public function calcSumPaymentFee(int $tanka, int $quantity) { $fee = 0; $fee = $tanka * $quantity; return $fee; } |
⑤その他コーディングルール、作法
if文の条件式などは、否定形よりも肯定形を使う
NG例とOK例を紹介します。
【NG例】否定形の条件式
|
1 2 3 4 5 |
if(!isset($a) && $b != 1) { //処理 } else { //処理 } |
【OK例】肯定形の条件式
|
1 2 3 4 5 |
if (isset($a) && $b === 1 ) { //処理 } else { //処理 } |
頭の中で条件式を追って考えるとき、
NG例の場合：「$aがissetでないときかつ$bが1でないときは〇〇、それ以外のときは△△」
OK例の場合：「$aがissetかつ$bが1のときは◇◇、それ以外のときは〇〇」
と考えると思います。
NG例の場合「issetでないとき」かつ「$bが1でないとき」「それ以外」、といったように一度否定形にして考える必要があるため、理解に時間がかかりやすくなります。
（可能な場合は）否定形ではなく肯定形を使うことで、「一度否定形にして考える」動作がなくなるのですんなり頭に入ってきて理解がしやすくなります。
比較を書くときは、変化する値を左に、安定した値を右に配置する
if (10 <= $a) や while(10 > $a)
よりも
if ($a >= 10) や while($a < 10)
のように、変化する値が左、安定した値が右にあるパターンのほうが読みやすくなることが多いです。
論理式をわかりやすくする
ド・モルガンの法則によると、
!(a || b || c) ＝(!a && !b && !c)
!(a && b && c) ＝ !a || !b || !c
が成り立ちます。
このように、複雑な論理式はできるだけシンプルな論理式に修正します。
NG例とOK例を紹介します。
【NG例】複雑でわかりにくい論理式
|
1 2 3 |
if (!($a && !$b)) { //処理 } |
【OK例】シンプルでわかりやすい論理式
|
1 2 3 |
if(!a || $b) { //処理 } |
まとめ
以上、開発をする上で気を付けている私なりのコーディング・プログラミングルールでした！
今後新たにコーデイングの作法を学んだときはまたブログにしたいと思います。
皆様のご参考になればうれしいです。
参考文献：リーダブルコード
- AWS CDK × CodeBuild × CypressでE2Eテストを自動化＆実行動画をS3に保存してみる - 2024-04-16
- AWS ECSでブルーグリーンデプロイメント！～デプロイメントタイプ別の動作比較～ - 2024-04-03
- AWS CDK × CodeBuildでLaravelのユニットテストを自動化 ＆ テストレポート出力してみる - 2024-04-03
- Amazon ECS on EC2のブルーグリーンデプロイ時にLaravelのセッション切れを起こさないための対策 - 2024-03-04
- AWS DeepRacerデビュー！初のレース参加から得た感想と気づき - 2023-12-20
【採用情報】一緒に働く仲間を募集しています
