ベストプラクティス、コーディングスタイル
ベストプラクティス、コーディングスタイル
誰でもSerendipityのプラグインやテーマに貢献することができます。
我々全員、これには本当に感謝しています。
新しいコントリビュータは、s9y.orgのフォーラムにぜひ気軽に訪問の上、自分の仕事を投稿ください。
人々の希望次第では、スパルタカス上でプラグインやテーマを管理できるようにするためのCVSアカウントが発行されることもあります。
テンプレートのコーディングスタイル
-
変更が絶対に必要なテンプレートファイルだけを変更してください。
Serendipityは標準テンプレートファイルを使うように戻せるので、例えばもしindex.tplファイルを変更する必要が無ければ、単にそのファイルを用意しないようにしてください。 -
あなたのテンプレートにconfig.inc.phpファイルやカスタム言語ファイルが必要なら、それらのファイルはできる限り小さく作るようこころがけてください。
パフォーマンスカウンタやPHPコードは、それぞれのページを訪問した時にそのコードが実行されるのがふさわしい場合にのみ使われるべきです。 - 全てのHTMLとCSSには (タブではなく) 4つのスペースによる適切なインデントを入れるようにしてください。
-
XHTML 1.1 Strictに準拠させてください。
XHTML 1.0 Transitionalでも問題ありませんが、HTML 4.0は本当にもう使うべきではありません。 - Mozilla FirefoxとMicrosoft Internet Explorer、もし可能ならOperaとSafari、その他マイナーなブラウザでもテンプレートがきちんと表示されるか確認するようにしてください。
-
外国語言語ファイルを提供する際は、テンプレートの「UTF-8」サブディレクトリにも言語ファイルを置いてください。
そしてそれらはUTF-8エンコードで保存してください。
全てのファイルは、できればUNIX用の改行 (\n) を使って保存してください。
プラグインのコーディングスタイル
-
SerendipityではPEARのコーディングガイドラインを使うことを試みています:標準コーディング規約。
縮約版:タブは使わず4つのスペースを使い、コードは常に適切にインデントしてください。
{ と } は使用が任意である場合にも常に含めてください。 -
あなたのプラグインが必要とする機能には、オブジェクト指向を使うようにしてください。
クラスのメソッドにアブストラクターを使えば、将来的な拡張も簡単にできるようになります。 - イベントフックは、あなたのプラグインが絶対に必要とするものを使うだけにしてください。
-
外部のURLから来る結果はキャッシュするようにしてください。
もしプラグインでRSSフィードを表示する場合、プラグインの実行毎に取得がされませんが、それでもたった毎回X分のことです。
設定オプションを提供して、ユーザ自身でキャッシュ期間 (X分) を設定できるようにしてください。 -
通常は、できる限りのパフォーマンスが出るように作っていってください。
(可能なら) 再帰的な関数コールは避けて参照変数を使うようにしてください ($eventDataはその一つです)。 -
いかなる出力メッセージも常に言語定数を利用して取り出してください。
あなたのプラグイン用の英語言語ファイルを必ず含めてください。 - プラグインの機能をアップデートする際には、Changelogという名前のファイルに変更内容を記してください。
- プラグインの説明を書きたくなったら、(<html>と<body>タグ無しで) HTMLマークアップし、それら全てをひっくるめてdocumentation_XX.htmlファイルとして保存してください。 XXは個別の言語のコードとなります。 UTF-8サブディレクトリにファイルのUTF-8バージョンを保存してください。 (注釈:これは未完成の仕様で、Serendipityではまだ未サポートですが、将来的に有効になるはずです!)
- もしあなたのプラグインがバックエンドにおけるボタン用コードを出力する場合は、常にserendipityPrettyButtonクラスを割り当ててください。 また入力タイプにもよりますがクラスを使ってください:タイプはinput_radio、input_checkbox、またはinput_buttonです。
- あなたのプラグインがバックエンドのサイドバーにカスタムメニューを出力する場合は、次のようなリスト項目を使ってください:<li class="serendipitySideBarMenuLink">
-
外部のコードを同梱する際は、プラグインの正確なライセンスを明示してください。
標準では、s9yのプラグインはBSDライセンスとなります。 -
できることなら小さなファイルを多数用意するのは避けてください。
スパルタカスは大き目のファイルを少数扱うのに向いています。 -
あなたのプラグインに外部コードへの依存がある場合、プラグインにそれらを同梱するか、またはあなたのプラグインが致命的なエラーや他の何かで処理中止にならないことを確実に確認してください。
何か不足しているものがあれば、常にそれをユーザーに通知しなければいけません。 -
PostgreSQLとSQLiteとMySQLで動くSQLステートメントだけを使ってください。
異なるシンタックスのために異なるステートメントが必要な場合は、SQLコードを分岐させてください。
もしカスタムBBコードのテーブルが必要なら、serendipity_db_schema_import() を使ってテーブルを間違いなく作ってください。 -
セキュリティ:XSS (クロス サイト スクリプティング) とSQLインジェクションへの対策をするようにしてください。
データベースにPOSTとGETから来る変数を格納する際には、必ず serendipity_db_escape_string() を使ってください。
POSTとGETから来る変数を出力する際は必ず htmlspecialchars() を適用させてください。
あなたのプラグインがバックエンドで管理タスクを使用する場合は、XSRF (クロス サイト リクエスト フォージェリ) 防御のために serendipityFormToken() 関数を確実に使ってください。 -
最後に:
既存のプラグインを調べてみてください。
これまでに動いているものが、あなたのプラグインのための草案としてうまく働くかもしれません。