コーディング指針

基本方針

こんなコードはよいコード

読みやすいことはよいことだ
- 見た目が単純だと読みやすい
- 皆がよく知っている構成は読みやすい (標準に従う。すでに知っているもの (Unix のコマンドとか) に従う。すでにあるものに従う)
書かないことはよいことだ
- 一画面で読める文字の量は一定
- 頭の中に同時にロードしてられるコードの量も一定 (せいぜい多くて数十行分程度)
- しつこい説明よりも、一つの決めごと
  - 変数の意味は変数名が表現しています (だから、説明のためのコメントは付けません)
  - プログラマは言語の基礎を知っています (だから、言語の標準機能・ライブラリ関数について逐一説明はしなくていいです)
  - などなど
タイプ量が少ないことはよいことだ
- タイプ量が少ないと単純に見えやすい
- 言語によらず、開発者が一定時間に打てるキーの上限はほぼ均一
- つまり、タイプ量が少ないと時間あたりの開発量が多くなる (かもしれない)

メソッドの書き方ガイドライン

メソッドの長さは 15 行程度におさえる
- 越えるときは、明確な理由があること
- 越えるときは、バグに注意
処理が何をしているかコメントをつけたくなったら、メソッドにする
条件判定部は式としてメソッドを定義する
基本的な名前の付け方
- オブジェクトのメソッドなら、object->動詞()
  
  $file->open()
- 関数なら、動詞目的語()
  
  openFile()

http://bit.ly/vp1oNn も参照

コードの書き方

コードが縦に長いのは悪です。横に長いのは場合によっては許容できます。この間には越えられない溝があります。

理由は、縦の長さはコードを読むときに省略できないためです。つまり、コードを読むスピードは縦の行数に制約されます。

一方、横に長いのは読み飛ばせます。読み飛ばせる条件は、左端だけ読めばその行の本質的な処理はすべて表現されていることです。

右のほうでごにょごにょやっていて、そこを読まないとコードの読解に支障がでるような場合 (副作用を伴う処理とか) は横に長くしてはダメです。

つまり、一行が一つの処理単位で完結している必要があります。

左端の 40 字くらいだけを眺めて読んでいってもちゃんと意味が通る形になっているのが読み手にやさしい良いコードです。

逆にいうと、一行を消費するということは読ませる価値のある一行にする必要があります。

コメントには「何をしているか」(What) ではなく、「なぜそのようにしなければならないのか」(Why) を書いてください。

または「なぜその変更が必要になったのか」を残してください。

「何をしているか」を補足しなければコードが読みにくい場合は、コードを変えて適切な単位でメソッドへと切り出してください。

その他

変数の宣言

変数の宣言や初期化は行いません。PHP の言語仕様から考えて、初期化しないほうがよりコーディングミスを捕捉できます。

値が束縛されないままに変数が参照されるようなコード (初期化はこのような変数の使い方でのみ意味がある) を書くのはやめましょう。変数の値がふらふらと変わるような変数の使い方はもっともバグを生む書き方です。C 言語のように言語仕様がやむを得ず初期化を求めることはたしかにあります (C 言語の未初期化の変数値はメモリの状況に依存し不定) 。一方、PHP では未定義の変数名は null に束縛されることが保証されており、初期化は不要です。また C 言語であっても、やはり変数の使い方を意識するほうがより重要です。初期化は単なる保険であり、PHP では保険すら必要ありません。

言語仕様としては求められないのに、変数宣言的にルーチンの冒頭に変数を並べることがあります。そして、実際にそれがある方がコードがわかりやすいときがあります。こんなときは、たいていルーチンが長すぎるか、変数名が実態を表していません。一読して使われる変数と役割が把握できないから宣言的なものがほしくなるのです。

変数の横にコメントで説明をつけるくらいなら、コメントと同じ意味の変数名を使いましょう。

ハンガリアンについて

ハンガリアン記法 (型名の prefix 付けたりする命名方法) 使わないの？という意見があるかもしれませんが、ハンガリアン記法は使いません。

ハンガリアン記法でわかる情報は、適切な名前を付ければほとんどカバーできます。string には string らしい変数名を、boolean には boolean らしい名前を、integer には integer らしい名前を付ければいいのです。

たとえば、xxx_path、xxx_name などという名前は、string 型をイメージさせ、integer や boolean であるとは思わないでしょう。xxx_count, xxx_size, xxx_length などというのは、integer (または他の数値型) をイメージさせます。is_ready ならば、boolean ですし、xxx_names であれば array 型でしょう。

ハンガリアン記法は、情報が増えることで本当に必要な情報の価値を薄めてしまいます。多くの場合、バグの原因は型が違うことではありません。より本質的な内容についてプログラミングをしていくためにもハンガリアン記法は使わない方がよいでしょう。

どうしても型のチェックが必要なのであれば、それは事前条件のチェックとしてテストを書くなり、バリデーションコードを書くなりすればリスクを回避できます。その一か所だか、二か所だかのためにすべてのコードに prefix を付けてまわるのは馬鹿らしいことです。

参考に挙げたアプリケーションハンガリアンについても、よい名前を付けることと本当に必要ならコードで表現すること (テストやバリデーションチェック) でほぼ対応ができます。

参考:

間違ったコードは間違って見えるようにする（アプリケーションハンガリアン）

sunaot/coding_guideline.md