@ -3,19 +3,16 @@ Yii 2 コア・フレームワーク・コード・スタイル
下記のコード・スタイルが Yii 2.x コアと公式エクステンションの開発に用いられています。
コアに対してコードをプル・リクエストをしたいときは、これを使用することを考慮してください。
私たちは、あなたが自分のアプリケーションにこのコード・スタイルを使うことを強制するものではありません。
あなたにとってより良いコード・スタイルを自由に選んでください。
私たちは、あなたが自分のアプリケーションにこのコード・スタイルを使うことを強制するものではありません。あなたにとってより良いコード・スタイルを自由に選んでください。
なお、CodeSniffer のための設定をここで入手できます: https://github.com/yiisoft/yii2-coding-standards
> Note: 以下では、説明のために、サンプル・コードのドキュメントやコメントを日本語に翻訳しています。
しかし、コア・コードや公式エクステンションに対して実際に寄稿する場合には、それらを英語で書く必要があります。
## 1. 概要
全体として、私たちは [PSR-2 ](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md ) 互換のスタイルを使っていますので、
[PSR-2 ](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md ) に適用されることは、すべて私たちのコード・スタイルにも適用されます。
全体として、私たちは [PSR-2 ](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md )
互換のスタイルを使っていますので、
[PSR-2 ](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md ) に適用されることは、
すべて私たちのコード・スタイルにも適用されます。
- ファイルは `<?php` または `<?=` のタグを使わなければならない。
- ファイルの末尾には一個の改行があるべきである。
@ -59,7 +56,7 @@ PHP コードは BOM 無しの UTF-8 のみを使わなければなりません
```php
/**
* ドキュメント
* Documentation
*/
class MyClass extends \yii\base\BaseObject implements MyInterface
{
@ -91,7 +88,8 @@ class Foo
- より読みやすいように、プロパティの宣言は空行を挟まずに続け、プロパティ宣言とメソッド宣言のブロック間には2行の空行を挟むべきです。
また、異なる可視性のグループの間に、1行の空行を追加するべきです。
- Private 変数は `$_varName` のように名付けるべきです。
- Public なクラス・メンバとスタンドアロンな変数は、先頭を小文字にした `$camelCase` で名付けるべきです。
- Public なクラス・メンバとスタンドアロンな変数は、
先頭を小文字にした `$camelCase` で名付けるべきです。
- 説明的な名前を使うこと。`$i` や `$j` のような変数は使わないようにしましょう。
例えば、
@ -119,17 +117,18 @@ class Foo
- 関数およびメソッドは、先頭を小文字にした `camelCase` で名付けるべきです。
- 名前は、関数の目的を示す自己説明的なものであるべきです。
- クラスのメソッドは常に修飾子 `private` 、`protected` または `public` を使って、可視性を宣言すべきです。`var` は許可されません。
- クラスのメソッドは常に修飾子 `private` 、`protected` または `public` を使って、可視性を宣言すべきです。
`var` は許可されません。
- 関数の開始の中括弧は関数宣言の次の行に置くべきです。
```php
/**
* ドキュメント
* Documentation
*/
class Foo
{
/**
* ドキュメント
* Documentation
*/
public function bar()
{
@ -145,8 +144,7 @@ class Foo
`Model` または `ActiveRecord` のようなクラス名を使うことも出来ます。
- 型付きの配列に対しては `ClassName[]` を使います。
- PHPDoc の最初の行には、メソッドの目的を記述しなければなりません。
- メソッドが何かをチェックする (たとえば、`isActive`, `hasClass` など) ものである場合は、
最初の行は `Checks whether` で始まらなければなりません。
- メソッドが何かをチェックする (たとえば、`isActive`, `hasClass` など) ものである場合は、最初の行は `Checks whether` で始まらなければなりません。
- `@return` は、厳密に何が返されるのかを明示的に記述しなければなりません。
```php
@ -164,7 +162,6 @@ class Foo
}
```
### 4.5 コンストラクタ
- PHP 4 スタイルのコンストラクタの代りに、`__construct` が使われるべきです。
@ -199,14 +196,14 @@ $str = 'こんな具合に。';
#### 変数置換
```php
$str1 = "こんにちは $username さん ";
$str2 = "こんにちは {$username} さん ";
$str1 = "Hello $username! ";
$str2 = "Hello {$username}! ";
```
下記は許可されません。
```php
$str3 = "こんにちは ${username} さん ";
$str3 = "Hello ${username}! ";
```
#### 連結
@ -367,23 +364,27 @@ $mul = array_reduce($numbers, function($r, $x) use($n) {
- ドキュメントの文法については [phpDoc ](http://phpdoc.org/ ) を参照してください。
- ドキュメントの無いコードは許容されません。
- 全てのクラス・ファイルは、ファイル・レベルの doc ブロックを各ファイルの先頭に持ち、クラス・レベルの doc ブロックを各クラスの直前に持たなければなりません。
- 全てのクラス・ファイルは、ファイル・レベルの doc ブロックを各ファイルの先頭に持ち、
クラス・レベルの doc ブロックを各クラスの直前に持たなければなりません。
- メソッドが実際に何も返さないときは `@return` を使う必要はありません。
- `yii\base\BaseObject` から派生するクラスのすべての仮想プロパティは、クラスの doc ブロックで `@property` タグでドキュメントされます。
これらの注釈は、`build` ディレクトリで `./build php-doc` コマンドを走らせることにより、対応する getter や setter の `@return` や `@param` タグから自動的に生成されます。
getter や setter に `@property` タグを追加することによって、これらのメソッドによって導入されるプロパティに対してドキュメントのメッセージを明示的に与えることが出来ます。
- `yii\base\BaseObject` から派生するクラスのすべての仮想プロパティは、クラスの doc ブロックで
`@property` タグでドキュメントされます。
これらの注釈は、`build` ディレクトリで `./build php-doc` コマンドを走らせることにより、
対応する getter や setter の `@return` や `@param` タグから自動的に生成されます。
getter や setter に `@property` タグを追加することによって、これらのメソッドによって導入されるプロパティに対して
ドキュメントのメッセージを明示的に与えることが出来ます。
これは `@return` で記述されているのとは違う説明を与えたい場合に有用です。
下記が一例です。
```php
< ?php
/**
* 全ての属性または一つの属性についてエラーを返す。
* @param string $attribute 属性の名前。全ての属性についてエラーを取得するためには null を使う。
* @property array 全ての属性に対するエラーの配列。エラーが無い場合は空の配列が返される。
* 結果は二次元の配列である。詳細な説明は [[getErrors()]] を参照。
* @return array 全ての属性または特定の属性に対するエラー。エラーが無い場合は空の配列が返される。
* 全ての属性に対するエラーを返す場合、結果は、下記のような二次元の配列になる。
* Returns the errors for all attribute or a single attribute.
* @param string $attribute attribute name. Use null to retrieve errors for all attributes.
* @property array An array of errors for all attributes. Empty array is returned if no error.
* The result is a two-dimensional array. See [[getErrors()]] for detailed description.
* @return array errors for all attributes or the specified attribute. Empty array is returned if no error.
* Note that when returning errors for all attributes, the result is a two-dimensional array, like the following:
* ...
*/
public function getErrors($attribute = null)
@ -404,7 +405,7 @@ $mul = array_reduce($numbers, function($r, $x) use($n) {
```php
/**
* Component は *property* 、*event* および *behavior* の機能を提供する基底クラスである。
* Component is the base class that provides the *property* , *event* and *behavior* features.
*
* @include @yii/docs/base -Component.md
*
@ -419,23 +420,25 @@ class Component extends \yii\base\BaseObject
```php
/**
* イベントに対してアタッチされたイベント・ハンドラのリストを返す。
* 返された [[Vector]] オブジェクトを操作して、ハンドラを追加したり削除したり出来る。
* 例えば、
* Returns the list of attached event handlers for an event.
* You may manipulate the returned [[Vector]] object by adding or removing handlers.
* For example,
*
* ```
* $component->getEventHandlers($eventName)->insertAt(0, $eventHandler);
* ```
*
* @param string $name イベントの名前
* @return Vector イベントにアタッチされたハンドラのリスト
* @throws Exception イベントが定義されていない場合
* @param string $name the event name
* @return Vector list of attached event handlers for the event
* @throws Exception if the event is not defined
*/
public function getEventHandlers($name)
{
if (!isset($this->_e[$name])) {
$this->_e[$name] = new Vector;
}
$this->ensureBehaviors();
return $this->_e[$name];
}
```
@ -453,7 +456,7 @@ public function getEventHandlers($name)
上記のリンクにクラス名やメソッド名以外のラベルを付けるためには、次の例で示されている文法を使うことが出来ます。
```
... [[header|ヘッダ・セル]] に表示されているように
... as displayed in the [[header|header cell]].
```
`|` の前の部分がメソッド、プロパティ、クラスへの参照であり、`|` の後ろの部分がリンクのラベルです。
@ -461,8 +464,8 @@ public function getEventHandlers($name)
下記の文法を使ってガイドにリンクすることも可能です。
```markdown
[ガイドへのリンク guide:file-name.md )
[ガイドへのリンク guide:file-name.md#subsection )
[link to guide guide:file-name.md )
[link to guide guide:file-name.md#subsection )
```
@ -492,8 +495,7 @@ public function getEventHandlers($name)
### 「何かをするな」を示す値
コンポーネントに対して「何かをしない」という設定を許可するプロパティは `false` の値を受け入れるべきです。
`null` 、`''`、または `[]` がそういう値であると見なされるべきではありません。
コンポーネントに対して「何かをしない」という設定を許可するプロパティは `false` の値を受け入れるべきです。`null`、`''`、または `[]` がそういう値であると見なされるべきではありません。
### ディレクトリ/名前空間の名前
@ -502,3 +504,4 @@ public function getEventHandlers($name)
- 機能や特徴を表す名前には単数形を使います (例えば、web)。
- 出来れば単一の語の名前空間にします。
- 単一の語が適切でない場合は、camelCase を使います。
Nobuo Kihara
6 years ago