cvs: peardoc /ja/chapters pear2cs.xml

http://cvs.php.net/viewvc.cgi/peardoc/ja/chapters/pear2cs.xml?view=markup&rev=1.1
Index: peardoc/ja/chapters/pear2cs.xml
+++ peardoc/ja/chapters/pear2cs.xml
<?xml version="1.0" encoding="utf-8" ?>
<!-- $Revision: 1.1 $ -->
<!-- EN-Revision: 1.5 Maintainer: takagi Status: ready -->
 <chapter id="pear2cs">
  <chapterinfo>
   <date>2007-11-26</date>
  </chapterinfo>
  <title>PEAR2 コーディング規約</title>
  <subtitle>PEAR2 で使用するコーディング規約</subtitle>
  <para>
   <itemizedlist>
    <listitem>
     <simpara>
     このドキュメントでは、PEAR2 リポジトリで使用するコーディングの標準規約を説明します。
     </simpara>
    </listitem>
    <listitem>
     <simpara>
     このコーディング規約の有効期限は 2008 年 3 月 1 日までです。
     有効期限を延長するには、PEAR Group によるレビューと修正が必要となります。
     </simpara>
    </listitem>
    <listitem>
     <simpara>
     PEAR2 リポジトリへの参加を希望するパッケージは、この標準規約を満たす必要があります。
     </simpara>
    </listitem>
    <listitem>
     <simpara>
     名前空間をサポートするバージョンの PHP のみをサポートします。
     おそらく PHP 5.3.0 以降となるでしょう。
     正確なバージョンがわかった時点で、この RFC を更新します。
     </simpara>
    </listitem>
    <listitem>
     <simpara>
     このルールには例外はありません。
     </simpara>
    </listitem>
    <listitem>
     <simpara>
     すべてのパッケージには package.xml 2.0 以降が必要となります。
     </simpara>
    </listitem>
   </itemizedlist>
  </para>


  <sect1 id="pear2cs.introduction">
   <title>導入</title>
   <para>
    PEAR 1.x は、PEAR インストーラ対応のコードを管理するという点で大きな成功を収めました。
    新たなインストーラである Pyrus は、これをさらに拡張して
    PEAR アプリケーション以外も扱えるように設計されており、
    単純に zip を展開してインストールするのと同様に動作します。
    PEAR2 リポジトリは、PEAR リポジトリよりも幅広いコーディング規約に対応できるようになっています。
    このドキュメントでは、<link linkend="standards">here</link>
    にある既存のルールやコーディング規約からの変更点をすべてとりあげます。
    ここにあげた規約とこれまでの規約が矛盾する場合は、新しい標準規約のほうを優先します。
    また、この規約は pear.php.net で管理している PEAR パッケージには何の影響も及ぼしません。
    あくまでも pear2.php.net で管理することになる PEAR2 パッケージに対してのみ有効となります。
   </para>

   <para>
    <methodname>require_once</methodname>
    を使用するとパッケージの構造についての制約が多くなり、
    PEAR パッケージの可能性を制限してしまいます。たとえば以下のような問題があります。

    <itemizedlist>
     <listitem>
      <simpara>
       <methodname>require_once</methodname>
       を使用すると、マルチプロセッサのウェブサーバを使用した大規模サイトでは
       10% 程度のパフォーマンスの低下が見られます。
       これは、待ち時間が増加することによるものです。
       しかし、シングルプロセッサのシステムを使用しているであろう大半のユーザにとっては、
       パフォーマンスの低下は最大でも 2% となります
       (Yahoo! のエンジニア Gopal Vijayaraghavan の計測より)。
      </simpara>
     </listitem>
     <listitem>
      <simpara>
      そのパッケージを使用するために、<literal>include_path</literal>
      の設定が必要となります。
      そのせいで、独自の <literal>include_path</literal> を持つ別のアプリケーションに
      PEAR をバンドルすることが難しくなります。
      また、必要なクラス群をすべてひとつのファイルにまとめることも難しくなりますし、
      PEAR パッケージを phar アーカイブにまとめる際にもソースコードの修正が必要となります。
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       トップレベルの <methodname>require_once</methodname> と条件付きの
       <methodname>require_once</methodname> を混用すると、
       APC のような opcode キャッシュ機能がうまく働かなくなります。
       APC は PHP 6 にバンドルされる予定です。
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <methodname>require_once</methodname> を相対パスで指定するには、
       <literal>include_path</literal>
       が適切に設定されている必要があります。つまり、
       <literal>include_path</literal>
       が適切に設定されていなければそのパッケージが使えなくなるわけです。
      </simpara>
     </listitem>
    </itemizedlist>
   </para>

   <para>
    <methodname>require_once</methodname> には、利点もあります。
    <itemizedlist>
     <listitem>
      <simpara>
       必要なファイルが存在しなければ Fatal Error: missing
       file X となるので、すぐに気づくことができます
       (<methodname>PEAR2_Autoload()</methodname> で
       <methodname>__autoload()</methodname> を使用することで対応できます)。
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       エンドユーザは、そのパッケージ内でどんなファイルを使用しているのかを気にせずにすみます
       (これもまた <methodname>PEAR2_Autoload()</methodname> で
       <methodname>__autoload()</methodname> を使用することで対応できます)。
      </simpara>
     </listitem>
    </itemizedlist>
   </para>

   <para>
    <methodname>require_once</methodname> をなくしてしまうと、その代わりに依存ファイル
    (パッケージ内のファイルあるいは外部のファイル) を読み込む仕組みが必要になります。
    ここでは、ふたつの方法を紹介します。
    <itemizedlist>
     <listitem>
      <para>
      PEAR2 の自動ロード機能
      (svn の
      <ulink
       url="http://svn.pear.php.net/wsvn/PEARSVN/Autoload/trunk/src/Autoload.php?op=file">
       ここ</ulink> にあります)
      と <methodname>__autoload()</methodname> を組み合わせて使用する
      </para>
     </listitem>
     <listitem>
      <simpara>
      必要なファイル群を読み込むための独自の仕組みを作成する
      </simpara>
     </listitem>
    </itemizedlist>
   </para>

   <para>
    いずれにせよ、必要なファイル群を読み込むのはエンドユーザ側の仕事となります。
    しかし、初心者向けには、<filename>PEAR2/Autoload.php</filename>
    を読み込みさえすればすべてうまくいくようになっています。
    このファイルは新規パッケージには常にバンドルされていますが、
    zip を展開してそのまま使用する形式の場合にのみ展開されます
    (pyrus は、点順に PEAR2 上の依存ファイルをインストールします。
    この中には、必要となるベースファイル <classname>PEAR2_Exception</classname>
    および <classname>PEAR2_Autoload</classname>
    が含まれます)。
    <programlisting role="php">
     <![CDATA[
<?php
  require '/full/path/to/PEAR2/Autoload.php';
  // これで、PEAR2 のすべてのパッケージが使えるようになります
?>
     ]]>
    </programlisting>
    <filename>PEAR2/Autoload.php</filename> は、include_path
    が正しい値に設定されていない場合に自動的に設定し、
    ユーザが定義していなければ自動的に
    <methodname>__autoload()</methodname> を宣言します。
   </para>
  </sect1>

  <sect1 id="pear2cs.rules">
   <title>規則</title>
   <para>
    この標準規約で使用する規則について説明します。
   </para>

   <sect2 id="pear2cs.rules.namespace">
    <title>名前空間プレフィックス</title>

    <para>
     すべてのクラスや関数は、少なくとも PEAR2 名前空間の配下にある必要があります。
     たとえば次のようになります。
    </para>
     <programlisting role="php">
     <![CDATA[
<?php
namespace PEAR2;
class MyClass {}
?>
     ]]>
     </programlisting>
    <para>
     クラスの名前空間をもっと長いものにすることもできます。
     たとえば、<classname>HTTP_Request</classname>
     クラスを作成する代わりに次のような構文を使用します。
    </para>
     <programlisting role="php">
     <![CDATA[
<?php
namespace PEAR2::HTTP;
class Request {}
?>
     ]]>
     </programlisting>
    <para>
     このようにすることで、名前空間があればクラス名のアンダースコアは不要となります。
     <classname>PEAR2_HTTP_Request</classname> のようなクラス名ではなく
     <classname>PEAR2::HTTP::Request</classname> となるのです。

     しかし、パッケージ名ではアンダースコアを使います。
     この場合のパッケージ名は 
     <classname>PEAR2_HTTP_Request</classname> となります。
    </para>
     <sect3 id="pear2cs.rules.namespace.requirement">
      <title>要件</title>
      <simpara>このルールには例外はありません</simpara>
     </sect3>
   </sect2>
  </sect1>
 </chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->