コードのスタイル、見た目
こんにちは、ニタです。
リーダブルコード第3回目は、「コードのスタイル、見た目」について書きたいと思います。
可読性が高く、読みやすいコードを書くには、分かりやすい変数、関数の命名規則の他に、見た目も意外と大事だと思います。
どんなにバグがなく高速に処理できるプログラムでも、ファイルを開いてみると、コードがゴチャゴチャしていて、理解するのに時間が掛かるようでは、修正する際困るのはコードを書いた自分であり、修正することになる自分を含む誰かです。
コードがキレイだと、さっと流し読みができて理解しやすく、修正、リファクタリングのしやすさに繋がると思います。
では、キレイなコードを書くためには何が重要なのでしょうか。
キレイなコードを書くためのポイント
キレイなコードを書くために気をつけるべきポイント・原則は、この3点だと思います。
- 読み手が慣れているパターン、一貫性のあるレイアウトを使う
- 似ているコードは似ているように見せる
- 関連するコードは1ブロックにまとめる
これらを実施するためには、実際にコードを書く段階でどのような事を行えばいいでしょうか。
一貫性のある簡潔な改行位置
例えば、関数の引数の指定など、コードの改行位置を統一することでコードを見やすくなる場合もあります。
以下は、投稿内容を取得する関数で、ニュースとブログの一覧を取得するコードです。
Post::getList()で必要な引数ごとに改行し、各引数の横にそれぞれの引数が何を意味するのかをコメントで書いてみました。
$news_list = Post::getList(
'news', // 投稿タイプ
20, // 1ページあたりの表示件数
1, // 表示ページ
true // 降順表示
);
$blog_list = Post::getList(
'blog', // 投稿タイプ
10, // 1ページあたりの表示件数
1, // 表示ページ
false // 降順表示
);
vimなどで、複数のファイルを同時に表示した際、1行あたりの文字数が限られてしまいます。
そのため、このように縦に長いコードの方が読みやすい場合も出てくると思います。
また、直接引数に値を入力せずに、分かりやすい変数名を決め、変数の上部や後ろにコメントで説明を追記しても良いですが、変数を作るまでもない場合はこのように書くのもアリかと思います。
ただ、上記のように同じメソッドを複数回呼び出す場合だと、縦に長くなるし、同じコメントを何回も書かなければなりません。
書き手も読み手も、ちょっと疲れますよね。
では、どう書けば良いか。
最初のメソッドだけコメントを書いて、以降は書かないというのも、コードのスタイルが統一されておらず、おかしいです。
コメントが書かれているメソッドが削除され、書かれていないメソッドだけが残ったら、途端に引数の内容が分からなくなるでしょう。
また、前述した「似ているコードは似ているように見せる」というポイントからも外れてきます。
このような場合は、下記のように仮の引数を使い、説明用のコメントを用意すると分かりやすくなると思います。
// Post::getList($post_type, $posts_per_page, $page, $is_desc_sort);
// 投稿形式, 1ページあたりの表示件数, 表示ページ, 降順表示するか
$news_list = Post::getList('news',20,1,true);
$blog_list = Post::getList('blog',10,1,false);
メソッドを使った整列、整頓
どんどんコードを書いていくうちに、コードが長く複雑になり、読みにくくなっていく場合もあるでしょう。
その場合、別のメソッドに分けることで、コードを簡潔になるケースもあります。
そうすることで、1つのコードの中で似たような処理を何度も書かなくてはいけない部分を、メソッドの呼び出しだけで済むようになります。
それにより、以下の様な副作用が生じる場合があります。
- コードが簡潔になり、可読性が上がる
- メソッドの呼び出しが簡潔になり、テスト用コードの追加が簡単になる
縦の線をまっすぐにする
縦の線、縦の並びを整えるということです。
ちょっと面倒ですが、こんな感じに並びをキレイにすると流し読みしやすくなります。
$detail = $request->post('detail');
$name = $request->post('name');
$url = $equest->post('url');
$phone = $request->post('phone');
$email = $request->post('email');
こういう感じで。
と、終わりたいところですが、上のコードの中でタイプミスがあります。
どこだか分かりますか？
縦の並びを意識して整列させると、こういったミスを見つけやすくなると思います。
（$urlの右辺、$requestが誤字）
でも、手間っちゃ手間です。時間に余裕がある時にやる感じの作業に感じます。
だからやらなくても良いかなとも思います。とは言え、流し読みはしやすくなるなとも感じるので、一概にやらない訳にもいかない作業です。
なので、時間的余裕と、今後そのコードを読む人への親切心がある場合に行う程度の作業と捉えておいてください。
一貫性と意味のある並び
「似ているコードは似ているように見せる」というポイントを実施するための書き方になります。
Webサイトのフォームのコーディングで、inputタグなど同じコードが複数ある場合、タグ内の属性の順番を統一させるなど、統一感を持たせることで、可読性が上がります。
<input type="text" name="name" value=""/> <input type="text" name="email" value=""/> <input type="text" name="tel" value=""/> <input type="text" name="address" value=""/>
タグごとに属性の順番がバラバラだと、コードを読み進めていくうちに一貫性のなさにイライラしたり、逆に意味があるのではないかと疑問に思ったりするかもしれません。
また、そのフォームでの入力内容を制御する側のコードでも、inputタグが書かれた順番に処理していくと、統一感が生まれ理解しやすいコードになると思います。
// 処理する順番を、inputタグの順番に合わせる。 $name = $_POST['name']; $email = $_POST['email']; $tel = $_POST['tel']; $address = $_POST['address'];
inputタグ順など基準となるものがない場合は、重要な項目順、アルファベット順など、ある一定の順番を決めておくといいと思います。
宣言をブロックにまとめる
コードを段落ごとに分割して読みやすくする、ということです。
ハンドラ系ならそれらで一塊に、ヘルパー系ならそれだけの塊でまとめます。
更に、先頭部分にコメントで何のブロックなのか、どういった処理を行うのかなど説明を書いておくと、より分かりやすくなるでしょう。
WordPressのテーマファイルの土台となるファイル群を自動生成する「_s」（underscores）というサービスがあります。
作成したいテーマ名を入力すると、ヘッダー、フッター、サイドバーや基本的なCSSファイルなどを生成してくれます。
その中のstyle.cssには、ファイル内でスタイル定義する内容の一覧表がコメントで書かれています。
更に項目ごと（ヘッダー部分、サイドバー部分）のスタイル定義を開始する前にコメントで、何のスタイル定義なのかを明記しており、手を加えやすい構成になっています。
個人的な好みと一貫性
最後に、個人的な好みに近いことです。
プロジェクト、チームごとの決まり事として、コーディング規約を決めておくと良いよという話です。
ifの「{」をifと一緒の行にするか、1行にするかとか、そういう話ですね。
if($hoge){
}
//もしくは
if($hoge)
{
}
コーディング規約は、個人的な好みで決める前に、使用するプログラム言語にも左右されるので、そこは注意しておく必要があります。
また、プロジェクトや社内ルールなどで決まったコーディング規約があるなら、それに合わせた方が良いでしょう。
規約が曖昧だったり、統一されていないと、コードが読みにくくなります。
プログラム言語、フレームワークによって、規約は様々あります。
まとめ
いつも書いていくと長くなるのですが、まとめてしまうとこんなに簡潔なことになります。
- 複数のコードブロックで、同じようなコードがあれば、シルエット（見た目）も同じようにすべき。
- コードの「列」を整列すれば、概要が把握しやすい。
- 意味ある順番を選び、常に守る。（例：inputの要素の並び）
- 空行を使い、大きなブロックを論理的な「段落」にする。
- コーディング規約などプロジェクト、チームごとの規約に準拠した書き方をする。
まずは仕様通りに、期待した動きができるようコードを書き進めるのが第一ですが、書き進めていくなかで、これまで書いてきたコードを振り返ったりする場合もあると思います。
その際に、ゴチャゴチャしすぎて分からなくなるようでは、どんなに動くコードでも、理解できなければ、修正できなければ、いざという時困ったことになります。
そのような事を防ぐためにも、日頃から少しずつ、今回のコードの整理を行うことで、読みやすいコードに近づくことができると思います。
それでは、また。
