コーディングスタイル
現在のところ、ソースコードはこのように記述されていなければいけない、といった厳しいルールは特にありません。ただし、DokuWiki にソースコードを追加する場合には、いくつか気をつけていただくことがあります。
括弧とインデント
論理的なブロックを示すためには 4 つのスペースを用いてインデントしてください。タブを用いたインデントはしないでください。多くのコードではまだ 2 つのスペースを利用しています。2 つのスペースにこだわるか、ファイル内のすべてのインデントを 4 つのスペースに変更するかのどちらかにすべきです。
開き括弧は制御文と同じ行に置くようにしてください (K&R スタイル)。閉じ括弧のインデントは、その括弧を開いた行のレベルに揃えてください。
例:
if ($foo == "bar"){ call_bar(); }elseif($foo == "baz"){ call_baz(); }else{ call_other(); }
改行と行末
改行記号は LF
としてください (UNIX 形式)。また、行末の空白はなるべく削除してください。Vim でこのルールを簡単に実現するためには、私の vimrc ファイルをご覧ください。
コメント
関数とクラスには、それぞれ phpDocumentor スタイルのコメントを付けてください。コメントは、最低限その関数の目的と著者名がわかるようにしておいてください。引数や返り値の説明もあるとなお良いのですが、これはそれらが明確でない場合のみ必須とします。もし既存の関数を改良する場合は、著者名の行を追加してください。
例:
/** * Check for foo in bar * * Checks if there is a foo in bar * * @author Joe Schmoe <joe@example.com> * @param string $in your input * @returns boolean true if foo in bar * */ function is_foo($in){ ... }
なお、これらのコメントは自動生成される API リファレンスで利用されます.
PHP ブロックの終了タグ
準備が不完全な状態での出力を防ぐため、すべてのソースファイルにおいて、PHP ブロックの終了タグ「?>
」を省略してください。少し変に思われるかもしれませんが、これは PHP マニュアルでも言及されていることです。
注: ファイル末尾における PHP ブロックの終了タグは省略可能です。むしろ、include()
や require()
でソースファイルを読み込む場合などはファイル末尾でうっかり改行やスペースが出力されることも無く、後で HTTP ヘッダを追加できる状態を保てるので、省略しておいたほうが良いこともあります。もし出力バッファを利用する場合でも、インクルードしたファイルで生成したコンテンツの後ろに不要な空白が付いたりしないので有益です。
コーディングスタイル違反のチェック
Git でチェックアウトした開発版には、PHP_CodeSniffer で利用するためのコーディング標準設定が _cs/DokuWiki
に含まれています。