cvs: peardoc /ja/chapters standards.xml

From: Date: Sat, 29 Apr 2006 23:38:53 +0000
Subject: cvs: peardoc /ja/chapters standards.xml
Groups: php.pear.doc 
Request: Send a blank email to pear-doc+get-7842@lists.php.net to get a copy of this message
haruki Sat Apr 29 23:38:53 2006 UTC Modified files: /peardoc/ja/chapters standards.xml Log: sync with en. and some improvements.

http://cvs.php.net/viewcvs.cgi/peardoc/ja/chapters/standards.xml?r1=1.5&r2=1.6&diff_format=u Index: peardoc/ja/chapters/standards.xml diff -u peardoc/ja/chapters/standards.xml:1.5 peardoc/ja/chapters/standards.xml:1.6 --- peardoc/ja/chapters/standards.xml:1.5 Thu Jun 30 12:12:05 2005 +++ peardoc/ja/chapters/standards.xml Sat Apr 29 23:38:53 2006 @@ -1,6 +1,6 @@ <?xml encoding="utf-8"?> -<!-- $Revision: 1.5 $ --> -<!-- EN-Revision: 1.35 Maintainer: haruki Status: working --> +<!-- $Revision: 1.6 $ --> +<!-- EN-Revision: 1.41 Maintainer: haruki Status: working --> <!-- CREDITS: hirokawa --> <chapter id="standards"> <title>標準コーディング規約</title> @@ -16,8 +16,8 @@ <para> 空白 4 つのインデントを使用します。タブは使いません。 PEAR コードの編集に Emacs を使用する場合、indent-tabs-mode を - nil に設定する必要があります。以下に、これらのガイドラインに基づき - Emacs を設定するモードフックの例を示します(PHP ファイルを編集する際に + nil に設定する必要があります。これらのガイドラインに基づき + Emacs を設定するモードフックの例を次に示します(PHP ファイルを編集する際に これがコールされるようにする必要があります)。 <programlisting role="elisp"> <![CDATA[ @@ -33,7 +33,7 @@ </programlisting> </para> <para> - 以下に、同様なことを行う vim ルールを示します。 + 次に、同様なことを行う vim ルールを示します。 <programlisting role="vim"> <![CDATA[ set expandtab @@ -55,7 +55,7 @@ <title>制御構造</title> <para> 制御構造には、if, for, while, switch 等があります。 - 以下に、最も複雑な制御構造である if 文の例を示します。 + 最も複雑な制御構造である if 文の例を示します。 <programlisting role="php"> <![CDATA[ if ((condition1) || (condition2)) { @@ -106,7 +106,7 @@ 関数は、関数名・開きカッコおよび最初のパラメータそれぞれの間には空白を置かず、 カンマとパラメータ間には空白を置き、最後のパラメータと閉カッコ およびセミコロンの間には空白を置かずにコールします。 - 以下に例を示します。 + 例を示します。 <programlisting role="php"> <![CDATA[ $var = foo($bar, $baz, $quux); @@ -129,7 +129,7 @@ <sect1 id="standards.funcdef"> <title>関数定義</title> <para> - 関数宣言は、以下のような <quote>one true brace</quote> と呼ばれる表記に従います。 + 関数宣言は、以下のような <quote>one true brace</quote> と呼ばれる表記にしたがいます。 <programlisting role="php"> <![CDATA[ function fooFunction($arg1, $arg2 = '') @@ -145,7 +145,7 @@ <para> デフォルト値を有する引数は、引数リストの終わりに置きます。 適切でない場合を除き、関数は、意味のある値を返すようにします。 - 以下に、やや長い例を示します。 + やや長い例を示します。 <programlisting role="php"> <![CDATA[ function connect(&$dsn, $persistent = false) @@ -176,7 +176,7 @@ <link linkend="standards.header">ヘッダコメントブロック</link> のセクションを参照してください。 詳細な情報は、 - <ulink url="&url.phpdocumentor;">&url.phpdocumentor;</ulink>にあります。 + <ulink url="&url.phpdocumentor;">&url.phpdocumentor;</ulink> にあります。 </para> <para> インラインドキュメント以外のコメントを書くことも推奨します。一般的な目安として、 @@ -193,11 +193,11 @@ <title>コードの読み込み</title> <para> クラスファイルを無条件で読み込む場合は、 - <function>require_once</function> を使用します。クラスファイルを - 条件付きで読み込む場合(例えば、factory メソッド)は、 + <function>require_once</function> を使用します。 + クラスファイルを条件付きで読み込む場合(たとえば、factory メソッド)は、 <function>include_once</function> を使用します。 こうすることで、クラスファイルが 確実に 1 度だけ読み込まれます。 - これらは、同じファイルリストを共有しており、 + これらは、ファイルリストを共有しており、 混用について心配する必要はありません。 <function>require_once</function> で読み込まれたファイルは、 <function>include_once</function> により再度読み込まれることはありません。 @@ -227,7 +227,7 @@ PEAR リポジトリに含まれるすべてのソースコードには、 各ファイルの先頭に <quote>ページレベル</quote> のコメントブロックを、 各クラスの直前に <quote>クラスレベル</quote> のコメントブロックを記述します。 - 以下にそれらの例を示します。 + それらの例を示します。 </para> <para> @@ -314,7 +314,7 @@ <listitem> <para> PHP のバージョンについては、ページレベルのコメントブロックに - 以下のいづれかを記します + 次のいづれかを記します </para> <informalexample> <programlisting role="docblock">. @@ -331,7 +331,7 @@ <listitem> <para> PEAR で利用できるライセンスには何種類かあります。 - 以下のいづれかを選択し、ページレベルもしくはクラスレベルのコメントブロックに + 次のいづれかを選択し、ページレベルもしくはクラスレベルのコメントブロックに 記述します。 </para> <informalexample> @@ -340,6 +340,7 @@ * @license http://www.freebsd.org/copyright/freebsd-license.html BSD License (2 Clause) * @license http://www.debian.org/misc/bsd.license BSD License (3 Clause) * @license http://www.freebsd.org/copyright/license.html BSD License (4 Clause) + * @license http://www.opensource.org/licenses/mit-license.html MIT License * @license http://www.gnu.org/copyleft/lesser.html LGPL License 2.1 * @license http://www.php.net/license/3_0.txt PHP License 3.0 </programlisting> @@ -376,12 +377,12 @@ ソースファイルの作者リストに、コード提供者の名前を追加するべきかどうか を定義する明確な規則はありません。一般的には、 <quote>相当な</quote> 部分(10%から20%のコード変更を意味します)の変更を - 行った場合に、作者とするようです。 + 行った場合に、作者に加えるようです。 関数のリライトや新たなロジックの提供の場合には、例外もありえます。 </para> <para> - 簡単なコードの整理やバグ修正は、作者リストに新たに人を追加する - までの理由にはなりません。 + 簡単なコードの整理やバグ修正は、作者リストに + 新たに人を追加するまでの理由にはなりません。 </para> </listitem> </varlistentry> @@ -464,7 +465,7 @@ <title>文字間隔ほか</title> <para> PEAR のソースコードを読みやすくするため、 - テキストやタグの順序や文字間隔は、上に示した例にしたがう必要があります。 + テキストやタグの順序や文字間隔は、前の例にしたがう必要があります。 これは、JavaDoc 標準を採用したものになっています。 </para> </sect2> @@ -606,7 +607,7 @@ <term>MAINT_<replaceable>n_n</replaceable></term> <listitem> <simpara> - (ブランチ, オプション)(例えば1.2の後に1.2.1といった) + (ブランチ, オプション)(たとえば 1.2 の後に 1.2.1 といった) <quote>マイクロリリース</quote> を行う際に、 メインの開発トランクが非常に活発で、マイクロリリースで 僅かな変更のみを行いたい場合に、ブランチを使用することもできます。 @@ -692,7 +693,7 @@ 関数には、パッケージ間の名前の衝突を避けるためにパッケージ名を接頭辞として 加えるべきです。(接頭辞の後の)名前の最初の文字は小文字で、 新しい単語を始める際の各先頭文字は大文字とします。 - いくつかの例を以下に示します。 + いくつかの例を示します。 <informaltable> <tgroup cols="4"> <tbody> @@ -710,7 +711,7 @@ プライベートなクラスメンバ (それが宣言されたクラスの内部からだけの使用を意図したクラスメンバ。 PHP は、プライベート名前空間をまだサポートしていません。)は、 - アンダースコア 1 つを前に付けます。例を以下に示します。 + アンダースコア 1 つを前に付けます。例を示します。 <informaltable> <tgroup cols="3"> <tbody> @@ -723,14 +724,32 @@ </tgroup> </informaltable> </para> + <para> + <note> + <simpara>次の内容は PHP5 に適用されます。</simpara> + </note> + プロテクテッドなクラスメンバ(すなわち、それが宣言されたクラス内、 + およびそのサブクラス内でだけ使用できるクラスメンバ)には、 + 前にアンダースコアを付けません。例を示します。 + <informaltable> + <tgroup cols="2"> + <tbody> + <row> + <entry><simpara>protected $somevar</simpara></entry> + <entry><simpara>protected function initTree()</simpara></entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> </sect2> <sect2> <title>定数</title> <para> - 定数は、常にすべて大文字で記述し、単語の区切りにはアンダースコアを + 定数は、すべて大文字で記述し、単語の区切りにはアンダースコアを 使用するべきです。使用されるクラス/パッケージを大文字で表した名前を 定数の接頭辞として付加してください。 - 例えば、<literal>DB::</literal> パッケージで使用する定数は、 + たとえば、<literal>DB::</literal> パッケージで使用する定数は、 すべて <literal>DB_</literal> で始めます。 <note> <simpara> @@ -745,7 +764,7 @@ <para> パッケージでグローバル変数を定義する必要がある場合、その名前は、 アンダースコアを前後に付けたパッケージ名で始めるべきです。 - 例えば、PEAR パッケージは、 + たとえば、PEAR パッケージは、 <literal>$_PEAR_destructor_object_list</literal> という名前のグローバル変数を使用します。 </para> @@ -802,16 +821,16 @@ <title>サンプルファイル (標準の Docblock コメントを含む)</title> <para> 数多くの人が PEAR パッケージのソースコードを読みます。 - また、他の人が将来、パッケージの開発者として加わるかもしれません。 + また、将来、他の人がパッケージの開発者として加わるかもしれません。 ですから、皆の人生を楽にするには、コードや docblocks を規約にしたがって整えておくことが重要となります。 - 予期した場所にあれば、欲しい情報をすばやく見つけ出すことができるからです。 + 欲しい情報が予期した場所にあれば、すばやく見つけ出すことができるからです。 協力をよろしくお願いします。 </para> <para> 例に示す各 docblock には、Docblock コメントの記述方法について 詳しく述べられています。 - これらの指示に従うことは、2つの意味で重要です。 + これらの指示にしたがうことは、2 つの意味で重要です。 ひとつは、docblock が読みやすくなれば、ユーザや開発者が コードの内容についてすばやく理解できるようになるということ。 ふたつめは、PEAR のサイトでは、phpDocumentor により自動生成された @@ -1011,14 +1030,19 @@ * 'void' if nothing is returned. * * Here's an example of how to format examples: - * <sample> + * <code> * require_once 'Net/Sample.php'; * * $s = new Net_Sample(); * if (PEAR::isError($s)) { * echo $s->getMessage() . "\n"; * } - * </sample> + * </code> + * + * Here is an example for non-php example or sample: + * <samp> + * pear install net_sample + * </samp> * * @param string $arg1 the string to quote * @param int $arg2 an integer of how many problems happened.
« previous php.pear.doc (#7842) next »