|
|
|
@ -2,7 +2,7 @@ Yii2 コアフレームワークのコードスタイル
|
|
|
|
|
======================================= |
|
|
|
|
|
|
|
|
|
下記のコードスタイルが Yii 2.x コアと公式エクステンションの開発に用いられています。 |
|
|
|
|
コアに対してプルリクエストをしたいときは、これを使用することを考慮してください。 |
|
|
|
|
コアに対してコードをプルリクエストをしたいときは、これを使用することを考慮してください。 |
|
|
|
|
私たちは、あなたが自分のアプリケーションにこのコードスタイルを使うことを強制するものではありません。 |
|
|
|
|
あなたにとってより良いコードスタイルを自由に選んでください。 |
|
|
|
|
|
|
|
|
@ -22,7 +22,7 @@ Yii2 コアフレームワークのコードスタイル
|
|
|
|
|
- クラス内の定数はアンダースコアで区切られた大文字だけで宣言されなければならない。 |
|
|
|
|
- メソッド名は `camelCase` で宣言されなければならない。 |
|
|
|
|
- プロパティ名は `camelCase` で宣言されなければならない。 |
|
|
|
|
- プロパティ名は private である場合はアンダースコアで開始しなければならない。 |
|
|
|
|
- プロパティ名は private である場合はアンダースコアで始まらなければならない。 |
|
|
|
|
- `else if` ではなく常に `elseif` を使用すること。 |
|
|
|
|
|
|
|
|
|
2. ファイル |
|
|
|
@ -30,9 +30,9 @@ Yii2 コアフレームワークのコードスタイル
|
|
|
|
|
|
|
|
|
|
### 2.1. PHP タグ |
|
|
|
|
|
|
|
|
|
- PHP コードは `<?php ?>` または `<?=` タグを使わなければなりません。他のタグ、例えば `<?` は使ってはなりません。 |
|
|
|
|
- PHP コードは `<?php ?>` または `<?=` タグを使わなければなりません。他のタグの変種、例えば `<?` を使ってはなりません。 |
|
|
|
|
- ファイルが PHP コードのみを含む場合は、末尾の `?>` を含むべきではありません。 |
|
|
|
|
- 各行の末尾に空白を追加しないこと。 |
|
|
|
|
- 各行の末尾に空白を追加してはいけません。 |
|
|
|
|
- PHP コードを含む全てのファイルの名前は `.php` という拡張子で終るべきです。 |
|
|
|
|
|
|
|
|
|
### 2.2. 文字エンコーディング |
|
|
|
@ -51,26 +51,26 @@ PHP コードは BOM 無しの UTF-8 のみを使わなければなりません
|
|
|
|
|
|
|
|
|
|
- クラスは `CamelCase` で命名されなければなりません。 |
|
|
|
|
- 中括弧は常にクラス名の下の行に書かれるべきです。 |
|
|
|
|
- 全てのクラスは PHPDoc に従ったドキュメンテーションブロックを持たなければなりません。 |
|
|
|
|
- 全てのクラスは PHPDoc に従ったドキュメントブロックを持たなければなりません。 |
|
|
|
|
- クラス内のすべてのコードは単一のタブによってインデントされなければなりません。 |
|
|
|
|
- 単一の PHP ファイルにはクラスが一つだけあるべきです。 |
|
|
|
|
- 一つの PHP ファイルにはクラスが一つだけあるべきです。 |
|
|
|
|
- 全てのクラスは名前空間に属すべきです。 |
|
|
|
|
- クラス名はファイル名と一致すべきです。クラスの名前空間はディレクトリ構造と一致すべきです。 |
|
|
|
|
- クラス名はファイル名と合致すべきです。クラスの名前空間はディレクトリ構造と合致すべきです。 |
|
|
|
|
|
|
|
|
|
```php |
|
|
|
|
/** |
|
|
|
|
* ドキュメンテーション |
|
|
|
|
* ドキュメント |
|
|
|
|
*/ |
|
|
|
|
class MyClass extends \yii\Object implements MyInterface |
|
|
|
|
{ |
|
|
|
|
// code |
|
|
|
|
// コード |
|
|
|
|
} |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
### 4.1. 定数 |
|
|
|
|
|
|
|
|
|
クラスの定数はアンダースコアで区切られた大文字だけで宣言されなければなりません。 |
|
|
|
|
例えば: |
|
|
|
|
例えば、 |
|
|
|
|
|
|
|
|
|
```php |
|
|
|
|
<?php |
|
|
|
@ -82,17 +82,17 @@ class Foo
|
|
|
|
|
``` |
|
|
|
|
### 4.2. プロパティ |
|
|
|
|
|
|
|
|
|
- Public なクラスメンバーを宣言するときは `public` キーワードを明示的に指定します。 |
|
|
|
|
- Public なクラスメンバを宣言するときは `public` キーワードを明示的に指定します。 |
|
|
|
|
- Public および protected な変数はクラスの冒頭で、すべてのメソッドの宣言に先立って宣言されるべきです。 |
|
|
|
|
Private な変数もまたクラスの冒頭で宣言されるべきですが、 |
|
|
|
|
変数がクラスのメソッドのごく一部分にのみ関係する場合は、変数を扱う一群のメソッドの直前に追加してもかまいません。 |
|
|
|
|
変数がクラスのメソッドのごく一部分にのみ関係する場合は、変数を扱う一群のメソッドの直前に追加しても構いません。 |
|
|
|
|
- クラスにおけるプロパティの宣言の順序は public から始まり、protected、private と続くべきです。 |
|
|
|
|
- より読みやすいように、プロパティの宣言は空行を挟まずに続け、プロパティ宣言とメソッド宣言のブロック間には2行の空行を挟むべきです。 |
|
|
|
|
- Private 変数は `$_varName` のように名付けるべきです。 |
|
|
|
|
- Public なクラスメンバーとスタンドアロンな変数は、先頭を小文字にした `$camelCase` で名付けるべきです。 |
|
|
|
|
- Public なクラスメンバとスタンドアロンな変数は、先頭を小文字にした `$camelCase` で名付けるべきです。 |
|
|
|
|
- 説明的な名前を使うこと。`$i` や `$j` のような変数は使わないようにしましょう。 |
|
|
|
|
|
|
|
|
|
例えば: |
|
|
|
|
例えば、 |
|
|
|
|
|
|
|
|
|
```php |
|
|
|
|
<?php |
|
|
|
@ -109,17 +109,17 @@ class Foo
|
|
|
|
|
- 関数およびメソッドは、先頭を小文字にした `camelCase` で名付けるべきです。 |
|
|
|
|
Functions and methods should be named using `camelCase` with first letter lowercase. |
|
|
|
|
- 名前は、関数の目的を示す自己説明的なものであるべきです。 |
|
|
|
|
- クラスのメソッドは常に `private`、`protected` または `public` を使って、可視性を宣言すべきです。`var` は許可されません。 |
|
|
|
|
- クラスのメソッドは常に修飾子 `private`、`protected` または `public` を使って、可視性を宣言すべきです。`var` は許可されません。 |
|
|
|
|
- 関数の開始の中括弧は関数宣言の次の行に置くべきです。 |
|
|
|
|
|
|
|
|
|
~~~ |
|
|
|
|
/** |
|
|
|
|
* ドキュメンテーション |
|
|
|
|
* ドキュメント |
|
|
|
|
*/ |
|
|
|
|
class Foo |
|
|
|
|
{ |
|
|
|
|
/** |
|
|
|
|
* ドキュメンテーション |
|
|
|
|
* ドキュメント |
|
|
|
|
*/ |
|
|
|
|
public function bar() |
|
|
|
|
{ |
|
|
|
@ -154,7 +154,7 @@ $config = [
|
|
|
|
|
]; |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
既存の変数の型を変えることは悪い慣行であるとみなされます。本当に必要でない限り、そのようなコードを書かないように努めましょう。 |
|
|
|
|
既存の変数の型を変えることは悪い慣行であると見なされます。本当に必要でない限り、そのようなコードを書かないように努めましょう。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```php |
|
|
|
@ -167,13 +167,13 @@ public function save(Transaction $transaction, $argument2 = 100)
|
|
|
|
|
|
|
|
|
|
### 5.2 文字列 |
|
|
|
|
|
|
|
|
|
- 変数およびシングルクォーツを含まない文字列には、シングルクォーツを使います。 |
|
|
|
|
- 文字列が変数および一重引用符を含まない場合は、一重引用符を使います。 |
|
|
|
|
|
|
|
|
|
```php |
|
|
|
|
$str = 'Like this.'; |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
- 文字列がシングルクォーツを含む場合は、余分なエスケープを避けるためにダブルクォーツを使ってもかまいません。 |
|
|
|
|
- 文字列が一重引用符を含む場合は、余計なエスケープを避けるために二重引用符を使ってもかまいません。 |
|
|
|
|
|
|
|
|
|
#### 変数置換 |
|
|
|
|
|
|
|
|
@ -206,7 +206,7 @@ $sql = "SELECT *"
|
|
|
|
|
|
|
|
|
|
### 5.3 配列 |
|
|
|
|
|
|
|
|
|
配列には、開発者は PHP 5.4 の短縮構文を使用しています。 |
|
|
|
|
配列には、私たちは PHP 5.4 の短縮構文を使用しています。 |
|
|
|
|
|
|
|
|
|
#### 添え字配列 |
|
|
|
|
|
|
|
|
@ -218,7 +218,7 @@ $sql = "SELECT *"
|
|
|
|
|
$arr = [3, 14, 15, 'Yii', 'Framework']; |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
一つの行に多すぎる要素がある場合は: |
|
|
|
|
一つの行には多過ぎるほど要素がたくさんある場合は: |
|
|
|
|
|
|
|
|
|
```php |
|
|
|
|
$arr = [ |
|
|
|
@ -243,9 +243,9 @@ $config = [
|
|
|
|
|
|
|
|
|
|
- 制御文の条件は括弧の前と後に一つの空白を持たなければなりません。 |
|
|
|
|
- 括弧の中の演算子は空白によって区切られるべきです。 |
|
|
|
|
- 開始の括弧は同じ行に置きます。 |
|
|
|
|
- 終了の括弧は新しい行に置きます。 |
|
|
|
|
- 単一行の文に対しても、常に括弧を使用します。 |
|
|
|
|
- 開始の中括弧は同じ行に置きます。 |
|
|
|
|
- 終了の中括弧は新しい行に置きます。 |
|
|
|
|
- 単一行の文に対しても、常に中括弧を使用します。 |
|
|
|
|
|
|
|
|
|
```php |
|
|
|
|
if ($event === null) { |
|
|
|
@ -263,7 +263,7 @@ if (!$model && null === $event)
|
|
|
|
|
|
|
|
|
|
#### switch |
|
|
|
|
|
|
|
|
|
switch には下記の書式を使用します: |
|
|
|
|
switch には下記の書式を使用します。 |
|
|
|
|
|
|
|
|
|
```php |
|
|
|
|
switch ($this->phpType) { |
|
|
|
@ -297,7 +297,7 @@ doIt('a', [
|
|
|
|
|
|
|
|
|
|
### 5.6 無名関数 (lambda) の宣言 |
|
|
|
|
|
|
|
|
|
`function`/`use` トークンと開始括弧の間の空白に注意: |
|
|
|
|
`function`/`use` トークンと開始括弧の間の空白に注意してください。 |
|
|
|
|
|
|
|
|
|
```php |
|
|
|
|
// 良い |
|
|
|
@ -308,7 +308,7 @@ $sum = array_reduce($numbers, function ($r, $x) use ($n) {
|
|
|
|
|
return $r; |
|
|
|
|
}); |
|
|
|
|
|
|
|
|
|
// bad |
|
|
|
|
// 悪い |
|
|
|
|
$n = 100; |
|
|
|
|
$mul = array_reduce($numbers, function($r, $x) use($n) { |
|
|
|
|
$this->doMagic(); |
|
|
|
@ -317,21 +317,21 @@ $mul = array_reduce($numbers, function($r, $x) use($n) {
|
|
|
|
|
}); |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
ドキュメンテーション |
|
|
|
|
-------------------- |
|
|
|
|
ドキュメント |
|
|
|
|
------------ |
|
|
|
|
|
|
|
|
|
- ドキュメンテーションの文法については [phpDoc](http://phpdoc.org/) を参照してください。 |
|
|
|
|
- ドキュメンテーションの無いコードは許容されません。 |
|
|
|
|
- ドキュメントの文法については [phpDoc](http://phpdoc.org/) を参照してください。 |
|
|
|
|
- ドキュメントの無いコードは許容されません。 |
|
|
|
|
- 全てのクラスファイルは、ファイルレベルの doc ブロックを各ファイルの先頭に持ち、 |
|
|
|
|
クラスレベルの doc ブロックを各クラスの直前に持たなければなりません。 |
|
|
|
|
- メソッドが何も返さないときは `@return` を使う必要はありません。 |
|
|
|
|
- メソッドが実際に何も返さないときは `@return` を使う必要はありません。 |
|
|
|
|
- `yii\base\Object` から派生するクラスのすべての仮想プロパティは、クラスの doc ブロックで `@property` タグでドキュメントされます。 |
|
|
|
|
これらの注釈は、`build` ディレクトリで `./build php-doc` コマンドを走らせることにより、 |
|
|
|
|
対応する getter や setter の `@return` や `@param` タグから自動的に生成されます。 |
|
|
|
|
getter や setter によって導入されるプロパティに対してドキュメンテーションのメッセージを |
|
|
|
|
明示的に与えるために `@property` タグを追加することが出来ます。 |
|
|
|
|
これは `@return` において記述されているのとは違う説明を与えたい場合に有用です。 |
|
|
|
|
例えば: |
|
|
|
|
getter や setter に `@property` タグを追加することによって、 |
|
|
|
|
これらのメソッドによって導入されるプロパティに対してドキュメントのメッセージを明示的に与えることが出来ます。 |
|
|
|
|
これは `@return` で記述されているのとは違う説明を与えたい場合に有用です。 |
|
|
|
|
下記が一例です。 |
|
|
|
|
|
|
|
|
|
```php |
|
|
|
|
<?php |
|
|
|
@ -341,15 +341,14 @@ $mul = array_reduce($numbers, function($r, $x) use($n) {
|
|
|
|
|
* @property array 全ての属性に対するエラーの配列。エラーが無い場合は空の配列が返される。 |
|
|
|
|
* 結果は二次元の配列である。詳細な説明は [[getErrors()]] を参照。 |
|
|
|
|
* @return array 全ての属性または特定の属性に対するエラー。エラーが無い場合は空の配列が返される。 |
|
|
|
|
* 全ての属性に対する配列を返す場合、結果は、下記のように、二次元の配列である: |
|
|
|
|
* 全ての属性に対するエラーを返す場合、結果は、下記のような二次元の配列になる。 |
|
|
|
|
* ... |
|
|
|
|
*/ |
|
|
|
|
public function getErrors($attribute = null) |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
>Note|注意: これ以降、読みやすさを考慮してドキュメンテーションの内容を日本語に翻訳していますが、 |
|
|
|
|
コアコードや公式エクステンションに対して寄稿する場合は、当然ながら、コメントは英語だけを |
|
|
|
|
使わなければなりません。 |
|
|
|
|
>Note|注意: ここでは読みやすさを考慮してドキュメントの内容を日本語に翻訳していますが、 |
|
|
|
|
コアコードや公式エクステンションに対して寄稿する場合は、当然ながら、コメントには英語だけを使う必要があるでしよう。 |
|
|
|
|
|
|
|
|
|
#### ファイル |
|
|
|
|
|
|
|
|
@ -407,14 +406,14 @@ public function getEventHandlers($name)
|
|
|
|
|
|
|
|
|
|
上記の例に見られるように、phpDoc コメントの書式設定には markdown を使っています。 |
|
|
|
|
|
|
|
|
|
ドキュメンテーションの中でクラス、メソッド、プロパティをクロスリンクするために使う追加の文法があります: |
|
|
|
|
ドキュメントの中でクラス、メソッド、プロパティをクロスリンクするために使える追加の文法があります。 |
|
|
|
|
|
|
|
|
|
- `'[[canSetProperty]] ` は、同じクラス内の `canSetProperty` メソッドまたはプロパティへのクロスリンクを生成します。 |
|
|
|
|
- `'[[Component::canSetProperty]]` は、同じ名前空間内の `Component` クラスの `canSetProperty` メソッドへのクロスリンクを生成します。 |
|
|
|
|
- `'[[yii\base\Component::canSetProperty]]` は、`yii\base` 名前空間の`Component` クラスの `canSetProperty` メソッドへのクロスリンクを生成します。 |
|
|
|
|
- `'[[Component]]` は、同じ名前空間内の `Component` クラスへのクロスリンクを生成します。ここでも、クラス名に名前空間を追加することが可能です。 |
|
|
|
|
|
|
|
|
|
上記のリンクにクラス名やメソッド名以外のラベルを付けるために、次の例で示されている書式を使うことが出来ます: |
|
|
|
|
上記のリンクにクラス名やメソッド名以外のラベルを付けるためには、次の例で示されている文法を使うことが出来ます。 |
|
|
|
|
|
|
|
|
|
``` |
|
|
|
|
... [[header|ヘッダセル]] に表示されているように |
|
|
|
@ -422,7 +421,7 @@ public function getEventHandlers($name)
|
|
|
|
|
|
|
|
|
|
`|` の前の部分がメソッド、プロパティ、クラスへの参照であり、`|` の後ろの部分がリンクのラベルです。 |
|
|
|
|
|
|
|
|
|
下記の書式を使って公式ガイドにリンクすることも可能です: |
|
|
|
|
下記の文法を使ってガイドにリンクすることも可能です: |
|
|
|
|
|
|
|
|
|
```markdown |
|
|
|
|
[ガイドへのリンク](guide:file-name.md) |
|
|
|
@ -440,11 +439,11 @@ public function getEventHandlers($name)
|
|
|
|
|
|
|
|
|
|
### `=== []` 対 `empty()` |
|
|
|
|
|
|
|
|
|
かの名時は `empty()` を使います。 |
|
|
|
|
可能な場合は `empty()` を使います。 |
|
|
|
|
|
|
|
|
|
### 複数の return ポイント |
|
|
|
|
|
|
|
|
|
条件のネストが込み入ってきた場合は、早期の return を使います。メソッドが短いものである場合は、特に問題にしません。 |
|
|
|
|
条件の入れ子が込み入ってきた場合は、早期の return を使います。メソッドが短いものである場合は、特に問題にしません。 |
|
|
|
|
|
|
|
|
|
### `self` 対 `static` |
|
|
|
|
|
|
|
|
@ -456,7 +455,8 @@ public function getEventHandlers($name)
|
|
|
|
|
|
|
|
|
|
### 「何かをするな」を示す値 |
|
|
|
|
|
|
|
|
|
コンポーネントに対して「何かをしない」という設定を許可するプロパティは `false` の値を受け入れるべきです。`null`、`''`、または `[]` は、そのような値として受け取られるべきではありません。 |
|
|
|
|
コンポーネントに対して「何かをしない」という設定を許可するプロパティは `false` の値を受け入れるべきです。 |
|
|
|
|
`null`、`''`、または `[]` がそういう値であると見なされるべきではありません。 |
|
|
|
|
|
|
|
|
|
### ディレクトリ/名前空間の名前 |
|
|
|
|
|
|
|
|
|